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

["Benjamin Stuhl" <sho_pi@hotmail.com>]

From: Gurusamy Sarathy <gsar@ActiveState.com>
>From a maintenance point of view, I think it would be best if the
>documentation appeared in the *.c files as a function header.  (The
>documentation generator should be able to grep them out easily enough.)

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
*/

>This way, people patching the sources can be expected to keep the
>docs up-to-date.  If the docs are in an obscure file, they'll probably
>overlook it.  Doing that would probably also make the sources more
>comprehensible.
>
>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
*/

>One of the goals is to make it possible (eventually) to have a way to
>build a DEBUGGING perl where all the macros will be real functions for
>ease of debugging.
>
> >Someone (or several someones) with a Win32, OS/2, or AIX machine
> >(they're the only ones I know of with enforced export lists for the Perl
> >library) should try this out by building and testing every XS
> >extension they have (especially Tk!) with a perl build with this patch. 
>If
> >the tests fail in DynaLoader or XSLoader, try
> >
> >nm extobj.o | grep Perl_ | less
> >
> >and look for functions that are not marked with flag 'A' in embed.pl 
>(change
> >it, rerun 'make regen_headers', rebuild perl, and try again).
> >Then please tell us what functions besides those I already marked are
> >already being used as part of the API so we can make it official.
>
>This would also be a good opportunity to convince extension authors about
>doing things in a better way than messing with the internals.  We can add
>additional API functions to facilitate that if we need to.  Eventually,
>I want to refine the API to the point where people have no casual reasons
>to use the PL_foo globals directly anymore.
>

I agree!

This patch is a replacement for the first one I sent - apply, as usual, with 
patch -Np1.

Enjoy!

-- BKS
______________________________________________________
Get Your Private, Free Email at http://www.hotmail.com

adoc.patch

---

Follow-Ups from:

Gurusamy Sarathy <gsar@ActiveState.com>

---

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

---