Re: [PATCH 5.5.63] Autogenerate API docs, define Perl API

[Gurusamy Sarathy <gsar@ActiveState.com>]

On Fri, 14 Jan 2000 12:30:40 PST, "Benjamin Stuhl" wrote:
>Ok, here's a modified version. It now uses a markup format I call
>Autodoc to put docs in comments near each function or macro (with the
>xsubpp-generated things stuck in XSUB.h). The format is very simple
>and is documented in Porting/autodoc.pod. Here's an example:
>
>/*
>AUTODOC BEGIN newAV
>
>C<newAV> creates a new, empty AV.
>
>AUTODOC END
>*/
[...]
>>Second, I think macros and the other missing parts of the API that were
>>in the "API LISTING" but were missing in embed.pl should simply be added
>>to the DATA section of embed.pl (i.e. not create an additional file).
>>Treat the macros as though they were functions, and specify their return
>>type, argument list, etc.  (Some macros that modify their arguments
>>may need special treatment.)
>
>Rather that doing that, I put the documentation right in the headers.
>Using Autodoc with macros takes a few more lines, but that's it:
>
>/*
>AUTODOC BEGIN macro
>AUTODOC FLAGS Am
>AUTODOC RET void
>AUTODOC ARGS int a|float b|char c
>
>this macro does some stuff and is part of the Perl API
>
>AUTODOC END
>*/

Are the BEGIN and END things really needed?

In the interests of not making it too verbose to type, I think we
should keep the format compact.  And I'd just use pod-like syntax,
so we can leverage Pod-Parser:

    /*
    =proto Am|void|macro|int a|float b|char c

    This macro does stuff.  See L<function>.

    =cut
    */

The stuff after the flags could be made optional for functions, because
the prototype is right there after the comment.  We can eliminate the
DATA section in embed.pl altogether this way. :-)

Excellent work, thanks.


Sarathy
gsar@ActiveState.com

---

Follow-Ups from:

Tim Bunce <Tim.Bunce@ig.co.uk>

References to:

"Benjamin Stuhl" <sho_pi@hotmail.com>

---

[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index][Thread Index][Top&Search][Original]

---