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

[Gurusamy Sarathy <gsar@activestate.com>]

On Wed, 12 Jan 2000 12:56:05 PST, "Benjamin Stuhl" wrote:
>This patch to embed.pl makes it only add functions marked as being
>part of the API to the various export mechanisms (global.sym, perlapi.c, 
>etc.), and also makes it autogenerate a new documentation file, perlapi.pod. 
>For the moment, this is nothing more that the API listing from perlguts.pod, 
>but it makes it easier to document new
>functions. Simply add 'd' to the function's flags in embed.pl, add an
>entry about it in pod/apidocs.in, rerun embed.pl, and presto! it's 
>documented.

Great work in general, but I'd like to see a couple of changes.

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.)
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.)

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.

Thanks for the work!


Sarathy
gsar@ActiveState.com

---

References to:

"Benjamin Stuhl" <sho_pi@hotmail.com>

---

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

---