perl-docs-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Gerald Richter" <rich...@ecos.de>
Subject Re: Autogenerating XS code and Docs
Date Thu, 13 Jun 2002 04:42:35 GMT
Hi,
> >
> > Yes, there are part like this, which still need much manual writing, on
> > these other side a lot of
> > http://perl.apache.org/release/docs/2.0/api/mod_perl-2.0/APR/Table.html
can
> > be autogenerated (comapre the output I send and your $table->add)
>
> most of the doc is still manually created, the function descriptions and
> args are usually don't take much space. But I do agree that it helps a
> lot. At least to create the basic docs and extend them afterwards as
> time allows.
>

I done some quick comparing and a lot of text seems just to be copy&paste...

Of course any autogenerated doc need to be reviewed and will need manual
modfications.
....
>
> Two problems here:
>
> 1. the pods will be read by people, and perldoc won't know how to handle
> autodoc. Or even worse those reading the source will have to get through
> a lot of noise.
>

perldoc will just ignore any =for which is not for the current translator. I
agree to you that you get some noise in the source.

> 2. I don't believe it's possible to use the generated docs without
> manual adjustments. You forget that at the maps level we change
> arguments, for which there is no docs. Also we don't want to be stuck
> with whatever comments httpd people have written, because they might be
> not good enough or for some other reason we will want to change them.
> Restricting us to a use as-is doesn't sound like a good idea to me.
>

I don't want to do any retricting here. I want to be able to change any
single lettter if necessary, but I also want to autogenerate as much as
possible. XSBuilder knows about all the changes that are done for the Perl
API, because it creates this Perl API. There are some few functions, where
XSBuilder doesn't know anything because they are totaly handcoded, but they
have to be documented manualy anyway.

>
> No, you maintain a single copy of each file. The autogenerated copies
> are autogenerated and you want to keep the previous copy so you can run
> the diff.

ok, when I wrote maintain I don't mean maintain the content, but keep them
somewhere at a public place, so more people are able to do that job.

> Notice that you will have to diff only when you update the
> maps (running source_scan), and the diff will be autogenerated and files
> automatically replaced.
>

You have to review the result anyway, but you also have to copy&paste (and
maybe modify) the diffs to the "real" document. I would like to automate
this copy&paste work too.

For now I don't have an idea that is really better then your diff method, so
I think we should start with it and maybe we come up with something better
later on.

>
> >>>For the XS genaration stuff there some issue with pTHX_ parameters
left,
> >>>which I hope to resolve soon. Also the whole stuff for generating
> >>
>
> Why not expanding this as a macro, which PPPort supplies. Does your
> version of source scan support macros expansions?

I don't use a C preprocsessor for this, so it don't have the full
capabilities of the C preprocessor, but of course you can do macro
expansions (and you need them for example for the Apache HOOK macros)

> So shouldn't this
> happen automatically? Actually you don't need PPPort for this, just
> including the right perl header files.
>

That was my first thought too, but when you do this you loose the
information that it originaly was pTHX_, it's now just like any other
parameter. Since the you don't know on which Perl versions the generated XS
code will be compiled, it's still necessary that the generated XS code uses
the xTHX macros, so expansion will happen at compile time and not at
generation time. So PPPort should be included in the generated output, which
makes sure that the output also works with older version of Perl, like
5.005.

> > What do you mean by "discuss the template"? The template for the pods
you
> > are talking about above?
>
> If you look at the existing 2.0 API docs, I've tried to follow the same
> layout (i.e. template), but I'm not entirely satisfied with it yet.
>

For that reason it is maybe a good idea to keep some more information in the
generated docs (maybe they have then to be postprocessed before they get
into the distribution), but when we keep what are the function defeintion,
parameters, comment, we will be able to convert it to any layout.

There is some idea at the p5ee project
(http://www.officevision.com/pub/p5ee/software/htdocs/P5EEx/Blue/podstyle.ht
ml), not sure if this helps anything. For example for a method you have
something like:

# Every method (each if applicable)
  =head2 <Method-Name>()
      * Signature:  <Sample-Usage-Illustrating-The-Signature>
      * Param:      <Param-Name> <Type> <In/Out> <Undef-OK>
      * Return:     <Return-Name> <Type> <Undef-OK>
      * Throws:     <Exception-Name>
      * Deprecated: <Since-Version> <Planned-Discontinue-Version>
      * Since:      <Version-Number>

If you use this schema you will be able to transform it any layout later,
because you keep this extra informations you need in the keywords like
"*Param:"

Gerald

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

Post:       Tulpenstrasse 5         D-55276 Dienheim b. Mainz
E-Mail:     richter@ecos.de         Voice:    +49 6133 925131
WWW:        http://www.ecos.de      Fax:      +49 6133 925152
-------------------------------------------------------------




---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org


Mime
View raw message