Beefy Boxes and Bandwidth Generously Provided by pair Networks
Clear questions and runnable code
get the best and fastest answer

Re: documentation best practices for internal modules

by Discipulus (Monsignor)
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 all is quiet...

How do I use this? | Other CB clients
Other Users?
Others examining the Monastery: (11)
As of 2018-07-23 14:11 GMT
Find Nodes?
    Voting Booth?
    It has been suggested to rename Perl 6 in order to boost its marketing potential. Which name would you prefer?

    Results (469 votes). Check out past polls.