Beefy Boxes and Bandwidth Generously Provided by pair Networks
The stupid question is the question not asked

comment on

( #3333=superdoc: print w/replies, xml ) 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.

In reply to Re: documentation best practices for internal modules by Discipulus
in thread documentation best practices for internal modules by hotshoe

Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":

  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.
  • Log In?

    What's my password?
    Create A New User
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others browsing the Monastery: (9)
    As of 2020-12-04 23:33 GMT
    Find Nodes?
      Voting Booth?
      How often do you use taint mode?

      Results (63 votes). Check out past polls.