perl-docs-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Gerald Richter - ecos gmbh" <>
Subject Re: Autogenerating XS code and Docs
Date Wed, 12 Jun 2002 10:04:12 GMT

> Gerald Richter wrote:
> > Since the whole Apache API is well documented in this way, it should be
> > possible to autogenerate most of the mod_perl API documentation from
> > informations. It would be necessary that somebody writes a tool that
> > this informations, brings it together with some manualy maintained pod
> > generates the pods out of it. This shouldn't be to hard to do.
> Can you please elaborate on this "merging manually maintained pod with
> autogenerated pod" part? I don't see how this can be done easily.
> e.g. for this doc that I've added recently:
> there is very little to be re-used from the apache docs, may be 5%.

Yes, there are part like this, which still need much manual writing, on
these other side a lot of can
be autogenerated (comapre the output I send and your $table->add)

> I guess what we need is sort of a template for the API documentation,
> which will be automatically filled with autogenerated docs.


> When such a
> doc is created for the first time, it's copied away to the place where
> the final pod should be and filled in with manual craft. This
> autogenerated file should be stored somewhere, so the next time the doc
> is autogenerated again (if the Apache API changes) we will be able to
> create a diff against docs that were autogenerated before (e.g. on every
> release) and merge manually the changes (notice that the diff is done
> against the doc autogenerated in the previous time, not the final pod).
> That's how I see it working. So we keep in cvs:
> 1) WrapXS/Apache/RequestRec/RequestRec.pod.last
> 2) WrapXS/Apache/RequestRec/RequestRec.pod
> 3) docs/api/mod_perl-2.0/Apache/RequestRec.pod
> 1) autogenerated last time and already merged into 3)
> 2) generated now, so we can diff 2) against 1) and merge into 3)
> 3) the real pod, manualy edited.

My idea is a little different. We start with the auto generated pod. The
generator tool adds some marks to every piecs it does, like

=for autodoc start apr_table_add_blablba

=for autodoc end apr_table_add_blablba

now you do your hand editing. When you rerun the autogeneration, it simply
replaces the part between the marks and leaves the rest untouched and maybe
it prints out a list what has changed, so you are able review the changes

Maybe your idea with diffs it better, because there isn't so much noise in
the pod itself, on the other hand you have to maintain serveral copies of
every file and I am not sure how much work it will be to manualy review
after the diff.

That's only a rought idea, maybe somebodyelse has another idea how to handle

> > For the XS genaration stuff there some issue with pTHX_ parameters left,
> > which I hope to resolve soon. Also the whole stuff for generating
> > is missing yet.
> Devel::PPPort?

This isn't a issue in the generated XS code (where Devel::PPPort could be
usefull), but an issue with code parser/generator, because you have a
function like

foo (pTHX_ int a, char b)

where pTHX_ is an type and an vaiable name and has no comma, so it has to be
handled special. Parsing now works correct, but I have add the special
handling in the code generator.

> Another question I have:
> In order to use ExtUtils::XSBuilder we need to have it in mod_perl. So
> does that mean that we cannot use it before mod_perl replaces its
> proprietary WrapXS with ExtUtils::XSBuilder?

I currently have it installed in parallel, have made a symlink to the
mod_perl xs directory to get the map files. This way it's easy to let it run
and genearte the files. That way you can prodcuse the informations for the
docs and if you want to try out the generated xs code, you just copy over
the WrapXS directory (which currently compiles, but some functions are
missing due to the pTHX_ problem, so it will not run)

So no problem to use it before it's fully integrated into mod_perl. If
anybody wants to try it out, I get give more detailed installation
instruction, or if there are more then one or two poeple use it, even add
some automatic way.

> And of course we need to discuss the template, but this can be done
> later when and if we start deploying ExtUtils::XSBuilder.

What do you mean by "discuss the template"? The template for the pods you
are talking about above?


Gerald Richter    ecos electronic communication services gmbh
Internetconnect * Webserver/-design/-datenbanken * Consulting

Post:       Tulpenstrasse 5         D-55276 Dienheim b. Mainz
E-Mail:         Voice:    +49 6133 925131
WWW:      Fax:      +49 6133 925152

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message