Beefy Boxes and Bandwidth Generously Provided by pair Networks
Don't ask to ask, just ask

Re: documentation best practices for internal modules

by Discipulus (Abbot)
on Jan 08, 2018 at 07:58 UTC ( #1206884=note: print w/replies, xml ) Need Help??

in reply to documentation best practices for internal modules

Hi hotshoe and welcome to the monastery!

I'm not the best one here around to answer your question, but with my limited experience to document a module, even a sub one (as you call them) is always a plus and something worth to be done.

Primarly because you as author will be the first consumer of documentation later on when you will have forgotten all details of the sub modules.

In second place an eventual user of the main module can be interested or in the need to know how Foo::Bar exposes it's functionalities to Foo and will be grateful to you to find what they need in the docs, instead of reading your source code.

Third the submodule doc is the place where to state clearly that the module must not be called directly and you put this in the synopsis and in the very beginning of the doc. Then a short list of included functions and what they expect and what they return is the bare minimum you must put inside the submodule documentation.

Take one of many module that includes sub modules not intended to be called directly as, even if it is a bit particular case, the core module File::Spec Infact File::Spec::Win32 File::Spec::Unix File::Spec::Mac and company all have their own short but useful documentation.


There are no rules, there are no thumbs..
Reinvent the wheel, then learn The Wheel; may be one day you reinvent one of THE WHEELS.

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://1206884]
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others making s'mores by the fire in the courtyard of the Monastery: (6)
As of 2020-12-04 23:45 GMT
Find Nodes?
    Voting Booth?
    How often do you use taint mode?

    Results (63 votes). Check out past polls.