On Fri, Oct 04, 2002 at 01:35:15PM -0400, Erik Lechak wrote:
> If parrot decides to go the route of embedding documents in its C code.
> Please do not use POD! Find a C developer sitting next to you that does
> not know POD and ask them how they like the flow of the ops files.
> Someone suggested 'doxygen', I am sure there are several other
> document/comment styles out there.
For a large perl project, I wrote a filter which takes
perl-with-doxygen-comments and transforms it to mock C++ with doxygen
comments. Doxygen can be instructed to filter files, so this works just
like native perl support would.
It's not perfect, because you have to talk about your perl code as if it
were C++, but for large OO projects it's actually a good match and it
helps that you can at least document that methods are private or
protected, even though perl doesn't enforce it. Where it really shines
is when you've got lots of inheritance. Doxygen will generate the
complete list of all callable methods, as well as telling you that a
method shadows one in a superclass (and the other way around).
I'm in the process of writing a converter from doxygen-generated XML
into POD, so that every .pm file can be accompanied by a .pod file,
which makes sure that perldoc will keep working.
Let me know if you're interested in the half-finished stuff...
The syntax for comments looks like this:
## @fn private void debug(@args)
# A simple function for debugging. Prints the arguments to STDERR.
# @param args The stuff to be printed.
sub debug {
my(@args) = @_;
...
}
--
Bart.
