In <[EMAIL PROTECTED]>, [EMAIL PROTECTED] (Aaron Sherman) wrote:
>This bit of POD made me think about POD's lack of tabular formatting, a
>common idiom in technical documentation. I know POD is still in the
>wings, as it were, but I wanted to say this before I forget....
/me flings coffee cup against the wall [no, not Larry!].
Perl is getting a major overhaul. POD is... well... now we have
=COMMENT.
If anything drastic is happening to POD, I've missed it, but if Perl can
be made over, why not POD? Or rather, why not the concepts and attitudes
pertaining to documentation in general, and documenting Perl code in
particular? (Yes, one of the nifty things about POD is its simplicity,
so maybe it should be left alone -- and something new added to the mix;
after all, There Is More Than One Way To Document It.) Adding extra
=head levels and =tables (and rudimentary support for tables sounds like
a good idea to me) is evolutionary; all well and good, but surely there
are some grand revolutions waiting to be instigated.
One of the selling features (or one of the features that is always sold)
of POD is that you can mix it with your code. Except nobody does, at
least I can't recall that last time I saw a module that did that, and I
don't think I've ever really done that myself. The POD usually sits in
a lump at the end of the file.
Having the documentation next to the code it describes means when you
change your function, you can't as easily forget to update the docs, the
way you would with a separate file. It's a terrific idea, but the user
docs you typically get with a module don't necessarily match your
functions that closely, or in the same order. I suppose one idea was
that programmers' docs (like Input, Process, Output) would go in POD so
that you when you printed out your code, you got something nice to look
at instead of lots of lines of #blahblah. Except I never print out my
code, not nowadays, not very often. So it's easier (both reading and
writing) to just put a bunch of #comments in the code itself.
OK, there's one non-incremental idea: documentation that you can write
in one place and display in some completely different order. (Shades of
literate programming!) And although there are good reasons for keeping
the docs in the same file as the code, there are equal but opposite
reasons to keep it separate (if it's all piled up at the end of the file
anyway). What gets presented to the user as "one page" could be bits
and pieces from all over the place.
Another problem with plain old-fashioned documentation -- and no small
influence on programmers' dislike of such, I wager -- is that you're
always duplicating work: first you have to explain to the computer how
to do something, then you have to explain it again to the user. Not
conducive to laziness, impatience, and hubris. I don't know how much
can be done about this, because computers and humans think in such
different ways, but I have in mind things like Getopt::Declare. (Stuff
like Pod::Usage probably fits in here somewhere, too.)
Having a nice, compact way to declare sub signatures is good. Being
able to document those signatures, not just "nearby", but
*simultaneously*, would be great. It saves a bit on typing (probably),
a LOT on procrastination (probably -- I think the psychological aspects
cannot be emphasised too much in the conventional wisdom that
programmers are reluctant to document their work), and the impossibility
of the docs getting out of sync with the code is priceless.
Well, easier said than done. In the end, the answer might have to be
"Yeah, there are lots of brilliant things that *could* be done, but P6
and Parrot already take up so much effort that it ain't gonna happen --
unless you actually contribute something yourself, in which case Show Us
the Code, mister!" But hey, rousing a bit of rabble is easy, and
there's always the possibility that someone really clever will come up
with an idea that is brilliant *and* feasible.
- David "what's up, docs" Green
