Tonight I've been working on getting the headerizer to automagically
update the comment blocks for each function in a .c file (.pmc files
will come later). The goal here is twofold:
1) The documentation is always consistent, because the declaration-
based documentation is computer-generated, and
2) The documentation is always up-to-date, because humans don't have
to remember to update the comment blocks.
Right now, it only updates src/tsq.c, a source file I picked at random
for experimentation and public discussion. I made it make comment
blocks look like this:
/*
=item C<QUEUE_ENTRY * pop_entry>
Does a synchronized removal of the head entry off the queue and
returns it.
=cut
*/
PARROT_CAN_RETURN_NULL
QUEUE_ENTRY *
pop_entry(ARGINOUT(QUEUE *queue))
{
... function body...
I figured that the two big things that mattered in an item heading are
the return type and the function name. What do you think? Do we need
a list of arg names in the =item as well? A copy of the full
declaration? We certainly don't want the full declaration in the
=item itself because it would be absurdly long what with all the
PARROT_ macros and whatnot. But I could see it looking like:
=item C<QUEUE_ENTRY * pop_entry(queue)
Does anyone actually run something like perldoc src/filename.c to
look at the docs? I'm thinking that if nobody actually does that, we
could save the doc discussion until we're actually at a point where
we're generating docs. Right now, I think that what I've got as the
prototype above is 90% there, and gets rid of the tons of cut'n'paste
that are sprinkled throughout the C code.
Let me know your thoughts, so I can do more automation and run it on
the rest of the source files.
xoxo,
Andy
--
Andy Lester => [EMAIL PROTECTED] => www.petdance.com => AIM:petdance
