|laziness, impatience, and hubris|
Re: documentation best practices for internal modulesby Discipulus (Monsignor)
|on Jan 08, 2018 at 07:58 UTC||Need Help??|
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.