I've recently embarked on a quest to bring the POD (Plain 'Ole Documentation) in our shop up to some level of measurable quality (or at least density/quantity). I half-heartedly googled around and did a Super Search here at PM but didn't come up with much in the way of a standardized way to do POD. So I decided to write my own rules. Here's a first draft:
- All Perl modules should be documented with POD.
- All Perl scripts (anything with the shebang line) should be documented with POD.
- All POD documentation should include, at a minimum, the following =head1 sections:
- DESCRIPTION -- This should be a paragraph or two about the purpose(s) for the module/script and a high-level narrative about what it does and how it works.
- SYNOPSIS -- This should be an example as to how one would use a module or call a script.
- if the script is intended to be directly executed, it should also include a =head2 section for PARAMETERS, outlining each argument or parameter which can be passed to the script
- AUTHOR -- This should include at least the last name of the person who 'owns' or wrote the script or module.
- Each public method or subroutine should be documented, using an =item or =headN tag to identify it by name, matching the subroutine name.
- Private methods or subroutines can be commented rather than POD-ed, but their names should follow the leading underscore convention so they can be easily excluded from any coverage calculations.
- Additional POD =headN sections can be used optionally: METHODS, NAME, SEE ALSO, PUBLIC, PRIVATE, COPYRIGHT, etc.
- All POD should pass podchecker (POD::Checker) with no errors
I've rolled my own customized substitute for POD::Coverage to profile our codebase documentation; it depends on (or at least expects) our code POD to adhere to these standards. So far it is being well-received by the other developers, although they may just be humoring me. :)
This seems to be an area where a little structure may go a long way ... I've tried to keep the standard pretty minimal to avoid makework. Recommendations welcome.
|
Re: POD Standards
by Old_Gray_Bear (Bishop) on Jan 06, 2006 at 21:02 UTC
|
About five years ago, I built a skeleton for Perl consisting of:
#! /usr/local/bin/perl
package FILL-IN-THE-NAME;
use strict;
use warnings;
CODE-GOES-HERE
1;
__DATA__
=pod
=head1 NAME
=head1 SYNOPSIS
=head1 DESCRIPTION
=head1 EXAMPLES
=head1 AUTHOR
=cut
Basically, I took the format of the UNIX man() pages and added the 'EXAMPLES' header. In addition, I have occasionally added 'TODO', 'NOTES', or 'SEE ALSO' headers when they were warranted. As I write the code, I update the POD.
I did this for a project that had all the ear-marks of becoming humongous (due to a certain lack of detail in the specifications and requirements). I could see myself quickly losing what little mind I had left if I didn't take steps. So I cooked up the template and started using it religiously.
Six months into the mess, I (finally) got another body assigned to the project. She was somewhat boggled by the idea of doing the Doco as you went along, but she came around.
What convinced her was her first bi-weekly 'status review meeting' with the "Project Team". I wandered in with a hundred and thirty-five pages of printed POD and spent the next three hours answering questions with variations on a theme of: 'Yes, that has been implemented, and see page mumble for the Doc'; and 'No, we can't do that, it will break the interface to X, unless we do the following .... ". (I wrote a bit of code that generated an Index from the 'NAME' headers and a Quick-Ref from the 'SYNOPSIS' headers to pull this off.)
Over the next eighteen months that 'structured documentation' saved our bacon so many times....
----
I Go Back to Sleep, Now.
OGB
| [reply]
[d/l] |
Re: POD Standards
by jimbojones (Friar) on Jan 06, 2006 at 19:53 UTC
|
| [reply] |
Re: POD Standards
by xdg (Monsignor) on Jan 06, 2006 at 20:36 UTC
|
| [reply] |
Re: POD Standards
by Perl Mouse (Chaplain) on Jan 06, 2006 at 23:50 UTC
|
Back in the good old days, pod2man would complain if you would not have a NAME section (excpet if you used the --lax option). All my documentation starts with NAME, SYNOPSIS and DESCRIPTION, as good manual pages do. For me, POD is primary used to generate man pages, and hence, it should follow the man pages conventions, hence the first three sections. And while in extreme cases a SYNOPSIS or a DESCRIPTION may be omitted, NAME would not be optional.
As for other sections, BUGS, SEE ALSO, COPYRIGHT/LICENSE, AUTHOR/MAINTAINER, and HISTORY, I use frequently. To a lesser extent: EXAMPLES, FILES (if additional files, typically configuration files, are used by the program), STANDARDS (if it conforms to standards), REFERENCES (for instance, to literature).
I presume that you list methods in a section METHODS. I would describe methods in the DESCRIPTION section. I've no idea what to expect from sections named PUBLIC and PRIVATE.
Private methods or subroutines can be commented rather than POD-ed, but their names should follow the leading underscore convention so they can be easily excluded from any coverage calculations.
I would not document private methods in the POD - as I said, for POD is to generate manual pages. That is, user documentation. It should document the interface: what to pass in to the program, subroutines or methods, and what to expect to happen in return (return values, side-effects). Discussion of the internals should be kept to a minimum, and only done if relevant. Hence, no private methods.
I don't like having a (potentially) large number of subroutines starting with an underscore. It looks unnatural and distracts. Doing so for the reason you mention is double bad. Programming languages shouldn't force arbitrary rules upon a programmer - it's the programming language that should be the slave, and the programmer the master. Not the other way around.
| [reply] |
Re: POD Standards
by petdance (Parson) on Jan 07, 2006 at 05:24 UTC
|
Please be sure to look at Test::Pod and Test::Pod::Coverage to automate your checking. I think that Test::Pod::Coverage ought to be extensible enough to handle your substitute.
| [reply] |
|
|
But if you include your POD tests as part of your distributed module, please consider using "skip unless require Test::Pod" logic.
I recently tried to install a module on my ISP and it installed and tested fine except the one test that depended on Test::POD which failed because Test::POD wasn't installed. Off CPAN.pm went to intall Test::POD and its many prereqs and somewhere in that very long list it came on something that needed Module::Build which refused to install (No, please let's not get into a MakeMaker/Build war). Yes the situation is b0rked and I should fix it, but I needed the original module running right away. I ended up doing a force install on the original module since its only failed test was the one requiring Test::POD.
Personally, I don't think it's the purpose of a distribution test to refuse to install because it can't test its POD. Hooray, your module that depends on Test::POD gets a perfect phalanx score. Boo, it cost me an extra twenty minutes to install it.
update Note that I am not recommending that you don't use Test::POD in your test, only that you don't require it for installation.
| [reply] |
|
|
I agree 100%. That's why the sample 4-line code that I suggest people use as t/pod.t does that exclusion.
| [reply] |
|
|
|
|
Re: POD Standards
by jZed (Prior) on Jan 06, 2006 at 19:29 UTC
|
I'm not sure how NAME could be considered optional. And I would consider COPYRIGHT to be essential for all but in-house modules (and important even then). | [reply] |
Re: POD Standards
by BrowserUk (Patriarch) on Jan 06, 2006 at 20:58 UTC
|
An alternative viewpoint is that for anything other than temporarily blocking out a chunk of code, POD should not be used. If these are programmers comments, then use comment cards.
If this is proper documentation, then use a proper documentation tool/markup. Something that knows how to:
- build tables;
- include diagrams;
- build tables of contents;
- create indexes;
- knows how to hyperlink;
If you use the lowest common denominator, you reap what you sow.
Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.
Lingua non convalesco, consenesco et abolesco. -- Rule 1 has a caveat! -- Who broke the cabal?
"Science is about questioning the status quo. Questioning authority".
In the absence of evidence, opinion is indistinguishable from prejudice.
| [reply] |
|
|
| [reply] |
|
|
Which is great if I want to have to write a parser to extract the documentation from the source file, convert it to another format, write it to a separate file and use another tool to view it--but why?
Why not just write it in that destination format to start with?
Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.
Lingua non convalesco, consenesco et abolesco. -- Rule 1 has a caveat! -- Who broke the cabal?
"Science is about questioning the status quo. Questioning authority".
In the absence of evidence, opinion is indistinguishable from prejudice.
| [reply] |
|
|
|
|
| |
|
So which is your preferrred proper documentation tool/markup?
| [reply] |
|
|
I am undecided--Doxygen looks pretty good, as do one or two of the wiki style tools--javadoc has a lot going for it (except the presence of java in the name:).
I really like the D language approach of allowing you to embed the code within an html document. The compiler simply ignores the surrounding HTML.
Haskell has a similar concept called Literate Haskell. Again, the source code is embedded within the documentation, and the compiler simple ignores everything except the source code, in this case indicated by the presence of a '>' in the first column of the line. If that isn't present, the compiler ignores the line.
Generally speaking, html is not the greatest markup in the world, but it is, or at least can be, pretty simple, as evidenced by this site, and there are dozens if not hundreds of tools around for editing, indexing, creating TOCs etc.
It is also as ubiquitous as anything is ever likely to be. It would be a rare machine these days that doesn't have some form of HTML browser available, even if it is a text-only one like lynx.
And the tools available go much further in accommodating the needs of the user. The browser I am using allows me to zoom the display (increasing the size of fonts and graphics using Ctrl-mousewheel, which is very useful for those who's eyesight is not so good. It also has a (downloadable) option to verbalise the contents--if you are completely blind. HTML is far from perfect, but it isn't going away anytime soon, and it does bring a wealth of useful tools with it.
And for the CLI-only crowd, lynx is far more usable when browsing nested documentation (like IO::Socket*/ LWP::*) than perldoc or man.
Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.
Lingua non convalesco, consenesco et abolesco. -- Rule 1 has a caveat! -- Who broke the cabal?
"Science is about questioning the status quo. Questioning authority".
In the absence of evidence, opinion is indistinguishable from prejudice.
| [reply] |
Re: POD Standards
by Anonymous Monk on Jan 06, 2006 at 21:05 UTC
|
Private methods or subroutines can be commented rather than POD-ed, but their names should follow the leading underscore convention so they can be easily excluded from any coverage calculations.
I use normal POD for subroutines, but use the "=begin" pod command designate a different translator to process those sections. I call my programmer documentation sections "programmers" docs, and I created a little "translator program" that just identifies the programmerdocs sections, strips them out, and passes them on to the standard pod translators.
That way, 'perldoc' gives me the user documentation, and my 'programmerdocs' script gives me the programmer documentation. This also allows a tester who is unfamiliar with the program to black box test each function without knowing the internals of the code: if the code doesn't match it's documentation, one of them needs fixing. This would be more useful if we had a testing department, but hopefully it's still of use to document.
I consistantly use the same template for documenting each function: first the name and arguments, then a one line description of the purpose of the function, then a detailed description, then the return values section, the global variables used (indicating read/write status), any preconditions (such as open filehandles, etc.), any postconditions (program termination conditions, warnings emitted, filesystem modifications, etc).
By documenting the pre and post conditions carefully, I usually end up thinking about the error handling of my functions (ie. "the routine emits a warning: but should it throw an exception instead?" or "The program dies if we hit an error condtion. Can/should it recover from this state instead?"). Thinking about formally documenting my decisions makes me think harder about the justifications I have for making each of those choices.
That's what works for me. I don't claim it should work for anyone else, though. :-)
--
Ytrew
| [reply] |
|
|
