SPUG:Re: Python and Doxygen

Geoffrey & Kristin Grosenbach glyph at mac.com
Wed Jan 22 20:38:07 CST 2003


> Python even comes with a command to load a module and assemble all the 
> doc
> strings from all the objects into something neat -- much like C++ and
> doxygen. Compare this with having to assemble the documentation from 
> scratch
> with perldoc. This saves a lot of typing if you want to go in later and 
> add
> or clean up the documentation. You won't have to write out the 
> parameters to
> the function, the base classes of your class, or anything like that.

It is downright embarrassing that Perl claims to be the mother of all 
parsing languages, and yet cannot come up with a decent way to parse 
it's own code (yes, I know this is part of the purpose of Perl6). I've 
worked with doxygen and JavaDoc, and I would greatly benefit from such a 
system for Perl. In fact, I was talking with Tim about this at Colin's 
party.

At minimum, it would be a script that would go through existing Perl 
code and build up POD sections for each function. At another level, it 
could look for function declarations and use those to make more thorough 
documentation.
    This gets a little fuzzy since all we really have is
    sub foo($$;\@)
which most people never use. Damian mentioned a style that I use, namely
    sub foo { my ($param1, $param2, @param3) = @_; }
which would be fully sufficient for a parser.

The result would be

=head2 foo ($param1, $param2, @param3)

Your comments go here.

=cut
sub foo { ...

I have a basic skeleton that does this, but I plan to refine it a bit 
more after I become unemployed at the end of next week! I'll post it to 
the list when I do.

But is this all that's required? We already have pod2html that builds 
hyperlinked documentation, though it would be nice to have a system that 
would build a meta-table of contents for multiple modules/classes (like 
JavaDoc). I've looked a little, but haven't seen anything that does this.




More information about the spug-list mailing list