Andy Lester wrote:
On Sep 18, 2007, at 9:04 AM, [EMAIL PROTECTED] wrote:
-FUNCDOC: mark_special
+=item C<mark_special>
This is a perfect example of why I want us to use FUNCDOC and not POD.
Who says that we are presenting functions as =item lists? Why is it
presented in C<>? =item C<mark_special> applies two levels of
presentation of documentation when we simply don't know how we want it
presented.
Paul, please hold off on changing any more FUNCDOC. The only value in
having embedded POD in C source code is the ability to say "pod2html
foo.c > foo.html", and that's just not much of a benefit when you
consider the amount of boilerplate we'd be re-adding.
We decided to remove FUNCDOC in May soon after it appeared. At the time
it only appeared in a couple of files, so I was surprised to it now
scattered over a couple of dozen files.
DRY is a good principle, but it's not the only principle to follow.
Another good principles is YAGNI: don't invent a new system until you
absolutely need it (your needs will change before you get there anyway),
and don't invent it at all if you can avoid it. Another good principle
is careful investment of developer resources: we will have to make the
investment in developing Parrot-based Pod parsing and formatting tools
for the bulk of the repository, so it doesn't make sense to duplicate
the effort and produce another set of tools for a different
documentation format.
Back to DRY again, the biggest objection to using Pod is creating an
exact duplicate of the function signature in the Pod. So, we won't do
that. We'll just list the name of the function in the Pod. We'll also
give some code examples of how to call the function (sane code examples
can't be generated, they always require a human brain). And, when Perl 6
Pod or Parrot's Pod tools are far enough developed, we'll start
automatically pulling in the full function signature from the code.
Allison
