nysus has asked for the wisdom of the Perl Monks concerning the following question:

Yet another Perl Question. I'm like a 5 year old, I know.

As an exercise to learn a distribution I'm interested in and to just get more knowledgeable in general, I figured I'd go through and study the code closely and take detailed notes on how the code works along the way and then, ideally, be able to share those notes with others.

I took a look a brief look AnnoCPAN but that only lets you add comments to documentation. Now, GitHub lets you make line by line comments on commits. I'm thinking maybe I could commit the distribution to GitHub and use that feature. Another option is to just crack open vim and make comments directly in the code but that doesn't let you easily create hyperlinks or do any kind of formatting.

But perhaps there is a tool out there that is designed specifically with this job in mind? Thanks.

$PM = "Perl Monk's";
$MCF = "Most Clueless Friar Abbot Bishop Pontiff Deacon Curate Priest";
$nysus = $PM . ' ' . $MCF;
Click here if you love Perl Monks

Replies are listed 'Best First'.
Re: Tools for annotating module code?
by eyepopslikeamosquito (Archbishop) on Dec 23, 2017 at 09:13 UTC

    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.

[reply]
Re: Tools for annotating module code?
by soonix (Chancellor) on Dec 23, 2017 at 08:23 UTC
[reply]

      Thanks for the input but perhaps I should give you a clearer idea of what I'm trying to accomplish.

      So, I'll give you a very simple example of what I mean by taking a look at just one line in the code: $WhateverModule::VERSION = '0.8';

      As someone who is pretty much a newb to versioning, this single line raises many questions for me. I've seen many different ways of doing versions in code and it's confusing to me. And I wonder how this way of getting the version into the code was settled on by the distribution. So I do a little googling and find two interesting articles related how to properly version your modules and I read them. I want to reference these articles in my notes about this particular line of code. And I did not know until recently that this line is automatically generated by some distribution generation software. So I want to also put that in my notes about this line as well.

      So, even with this one simple line, there can be quite a lot of knowledge laying hidden below it that is not readily obvious unless you are very experienced. I want to be able to easily reveal this kind of "hidden" knowledge in my annotations and six months later, after I might have forgotten, be able to refer to these notes.

      $PM = "Perl Monk's";
      $MCF = "Most Clueless Friar Abbot Bishop Pontiff Deacon Curate Priest";
      $nysus = $PM . ' ' . $MCF;
      Click here if you love Perl Monks

[reply]
[d/l]
[reply]
[reply]

Back to Seekers of Perl Wisdom