Beefy Boxes and Bandwidth Generously Provided by pair Networks
Do you know where your variables are?

Re: Tools for annotating module code?

by eyepopslikeamosquito (Bishop)
on Dec 23, 2017 at 09:13 UTC ( #1206098=note: print w/replies, xml ) Need Help??

in reply to Tools for annotating module code?

For general advice on how to document Perl code, chapter seven ("Documentation") of Perl Best Practices is worth a read, providing sound advice on separating user from technical documentation, how to subdivide your technical documentation, discursive documentation, algorithmic documentation, commenting, and more. See also Conway's "Create Standard POD Templates for Modules and Applications" suggestion in Ten Essential Development Practices.

Some further documentation tips derived from Writing Solid CPAN Modules:

  • Separate user versus maintainer documentation.
  • Ideally, a CPAN module's documentation should cover: Tutorial and Reference; Examples and Cookbook; Maintainer; How your module is different to similar ones; Change log; Notes re portability, configuration & environment, performance, dependencies, bugs, limits, caveats, diagnostics, bug reporting.
  • Document your module's errors in the user's dialect.
  • Add tests to your test suite to verify that examples given in your module's user documentation actually work.
  • Use Pod::Coverage to help ensure your module documentation is comprehensive.

Log In?

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

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

    Results (63 votes). Check out past polls.