David Mitchell wrote:
> 4. Are we all agreed that in addition to anything else (eg rfc281), at
> least some of the standard commentary should appear actually within the
> src file itself?
s/at least some/most, if not all/
> 5. Do *all* these comments need to be extractable, or only ones related
> to published APIs etc?
Initially the automaton creates them all extractable, and the coder
can depod the ones that are implementation details and should not be
published, as a measure more extreme than noting "This function is
an implementaion detail" in the mandatory comment for the function. Which
implies an at least implicit standard lexicon of flexibility to use in these
comments, ranging from "implements ISO standard interface" down to
"experimental - failed, remove during clean-up phase"
> 6. Can we leave the details of pod/apidoc/rfc281 until 1..5 have been
> agreed?
I can't. Can you? Altering a C prettyprinter to insert an extensible
standard comment template before each function definition would be even
easier than writing one from scratch. But what goes in that block of text,
beyond
/*
=pod
=head1 function $FunctionName returning $ReturnType
=head1 Named arguments: @ArgNameList
=cut
*/
????
