Woops - forgot to reply all (I'm on an irritating mixture of lists
which set reply-to and don't, and I never remember which is which).
Sorry!
---------- Forwarded message ----------
From: Matthew Walton <matt...@matthew-walton.co.uk>
Date: Tue, Aug 11, 2009 at 7:10 AM
Subject: Re: More flexible POD
To: Jon Lang <datawea...@gmail.com>
I'm not sure what it should be, but I do believe that there should be
a solution which allows elegant mixing of code and Pod. I want to
document my APIs by attaching the documentation to the methods in
question, otherwise the documentation won't get updated when the code
does (and if the code at work is anything to go by, won't get updated
at all anyway, but you can at least make it as easy as possible for
the people who do remember).
Attaching blocks of documentation to bits of code is something that
Javadoc's syntax gets very right.
The trouble is, if we just allow arbitrary whitespace before the start
of a Pod block:
class A {
=head2 foo()
Frobnicates the widget.
=end
method foo() { ... }
}
(modulo accurate Pod directives - I'm a bit hazy on how it works now,
I keep thinking I should be able to say '=method', but maybe that's a
matter for the Pod extractor).
Do we run the risk of causing problems if somebody does this:
my ($several, $lengthily-named, $variables)
= something-which-produces-a-list();
and the parser thinks 'hang on a sec, that's Pod'. This is
particularly bad for programmers who don't put spaces around their
binary operators (hah! We could enforce it!) and may cause
confuzzlement.
I don't think footnote-like references in the code would help
programmers keep the documentation up to date or help them in reading
it to comprehend the code when they come to maintain it, which I think
are the two key reasons to put your documentation right there in the
code. If you did do it though, you'd have to use named references
(probably valid Perl 6 identifiers), because numbers are just a
nightmare.
Matthew
