Tools for annotating module code?

[nysus]

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.

[eyepopslikeamosquito]

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.

[soonix]

The search term that comes to my mind is "literate programming". The first hit for perl literate programming is currently POD is not Literate Programming which should give you an idea wether its that what you are after (I think it is).

[nysus]

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.

[eyepopslikeamosquito]

I tend to use wikis for this sort of thing ... which admittedly may be the worst solution of all, except for all the others that have been tried so far. :)

From my limited googling on this topic, I get the feeling that this is a hard problem. At least, I couldn't find an example of an unqualified success story in this domain. For example, this post indicates that AnnoCPAN has hardly been an unqualified success. If anyone knows of a "successful" version of a similar concept to AnnoCPAN, please let us know.

References

• AnnoCPAN (perl.com article)
• A perldoc with annotations
• Can anyone suggest a Commenting system?
• Why not a "living" PerlDoc? Others have it, why not Perl?
• Re: Is Module::SafeVersion a Waste of Time?
• Re: What's up with AnnoCPAN? (suggests AnnoCPAN has not been an unqualified success)

[Anonymous Monk]

An Introduction to Literate Programming with perlWEB