You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs-dev@perl.apache.org by Gerald Richter <ri...@ecos.de> on 2001/10/07 20:05:07 UTC
Automatic generation of API doc ?
Hi,
as some of you have noticed I currently working on mod_perl's XS generation
system. One thing I have done is to replace C::Scan with an parser based on
Parse::RecDescend. One benefit of this is, that it is very easy to extent
what is parsed. So additionaly to the function and structures I currently
also extract the comments that belongs to these functions and structures and
lot of these comments contains the Aapache API documention in a special
format to create the documention files from them. So why don't we use these
comments to auto generate the pod files from them. The result has of course
to be reviewed manualy and corrections have to made, to adopt it to the Perl
interface, but this could be done in a similar way like it is done for the
XS code, by having some sort of map files, which contains additional docs or
changes on a function to function basis. That would saves a lot of
documention handwriting.
What do you think ?
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
Re: Automatic generation of API doc ?
Posted by Stas Bekman <st...@stason.org>.
Gerald Richter wrote:
> I have still some work with the XS generation and generation docs will be
> the next step, so it may take a few weeks until the work is done, but as
> soon as I have anything to show I will post here so you can comment on it,
> if this would be a reasonable way to go.
Sure, that sounds great!
> For now I can't tell you the format that these files will have, but maybe
> you first continue with writing docs that can't be auto gernerated (i.e.
> don't do any copy&paste work).
Currently we try to generate docs for the new functionality that gets
added. Ala "document as you code".
_____________________________________________________________________
Stas Bekman JAm_pH -- Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide http://perl.apache.org/guide
mailto:stas@stason.org http://ticketmaster.com http://apacheweek.com
http://singlesheaven.com http://perl.apache.org http://perlmonth.com/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: Automatic generation of API doc ?
Posted by Stas Bekman <st...@stason.org>.
Gerald Richter wrote:
> I have still some work with the XS generation and generation docs will be
> the next step, so it may take a few weeks until the work is done, but as
> soon as I have anything to show I will post here so you can comment on it,
> if this would be a reasonable way to go.
Sure, that sounds great!
> For now I can't tell you the format that these files will have, but maybe
> you first continue with writing docs that can't be auto gernerated (i.e.
> don't do any copy&paste work).
Currently we try to generate docs for the new functionality that gets
added. Ala "document as you code".
_____________________________________________________________________
Stas Bekman JAm_pH -- Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide http://perl.apache.org/guide
mailto:stas@stason.org http://ticketmaster.com http://apacheweek.com
http://singlesheaven.com http://perl.apache.org http://perlmonth.com/
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: Automatic generation of API doc ?
Posted by Gerald Richter <ri...@ecos.de>.
Hi Stas,
>
> I've posted a question about this issue a while ago, but received no
answer.
>
I remembered something, but didn't find it my mail folders anymore ....
> Your proposal is almost perfect. The only flaw it has is that once you
> do manual adjustments you cannot use the automatic retrieval anymore,
> since it'll overwrite your manual changes. You do address this issue,
> but I don't think it can work with free non-structured text. Or can it?
>
It will not do anything for you, but it can help.
> This kind of tool will be very useful for completed, stable .h files, to
> save a lot of time generating initial documentation. However currently
> httpd .h files still change a lot.
>
Then it's even more helpfull.
> Please look at the APR::Table and Apache::RequestRec pods that I've
> created already:
> docs/src/api/mod_perl-2.0/APR/Table.pod and
> docs/src/api/mod_perl-2.0/Apache/RequestRec.pod
>
> It would be very handy to have the tool you suggest for generating
> APR::Table since I had to copy-n-paste a lot from .h file.
Yes, I have looked at it, and for example the documentation for "make()"
function could be totaly autogenerated, without any adjustments needed.
> However this
> is not the case with Apache/RequestRec.pod where most of the doc is
> coming from nothing :)
>
Such things you still will have to write manualy.
> That's said, I'm looking forward to your new doc ripper and if you have
> a chance please look at the docs I've done already and tell me whether
> we should change the format of functions declaration/description.
>
My idea is to not directly write the pod files, but to have a kind of map
file. This file contains addtional information, for example some text to end
to the start or the end of a function documention, text which should be used
instead of the auto generated one etc. There will be one entry per
function/structure, so you can leave the auto generated docs for one
function, add some additional text to another and repleace to the text
totaly for a thrid function. Also it should be possible to add new sections
of functions which are not detected by the autogeneration code.
So you never edit the resuting pod file itself, because it will be
overwritten, but only these map files. This way you save at least the copy &
paste work and have only to write the other parts of the documentation which
could not be auto generated.
I have still some work with the XS generation and generation docs will be
the next step, so it may take a few weeks until the work is done, but as
soon as I have anything to show I will post here so you can comment on it,
if this would be a reasonable way to go.
For now I can't tell you the format that these files will have, but maybe
you first continue with writing docs that can't be auto gernerated (i.e.
don't do any copy&paste work).
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
Re: Automatic generation of API doc ?
Posted by Gerald Richter <ri...@ecos.de>.
Hi Stas,
>
> I've posted a question about this issue a while ago, but received no
answer.
>
I remembered something, but didn't find it my mail folders anymore ....
> Your proposal is almost perfect. The only flaw it has is that once you
> do manual adjustments you cannot use the automatic retrieval anymore,
> since it'll overwrite your manual changes. You do address this issue,
> but I don't think it can work with free non-structured text. Or can it?
>
It will not do anything for you, but it can help.
> This kind of tool will be very useful for completed, stable .h files, to
> save a lot of time generating initial documentation. However currently
> httpd .h files still change a lot.
>
Then it's even more helpfull.
> Please look at the APR::Table and Apache::RequestRec pods that I've
> created already:
> docs/src/api/mod_perl-2.0/APR/Table.pod and
> docs/src/api/mod_perl-2.0/Apache/RequestRec.pod
>
> It would be very handy to have the tool you suggest for generating
> APR::Table since I had to copy-n-paste a lot from .h file.
Yes, I have looked at it, and for example the documentation for "make()"
function could be totaly autogenerated, without any adjustments needed.
> However this
> is not the case with Apache/RequestRec.pod where most of the doc is
> coming from nothing :)
>
Such things you still will have to write manualy.
> That's said, I'm looking forward to your new doc ripper and if you have
> a chance please look at the docs I've done already and tell me whether
> we should change the format of functions declaration/description.
>
My idea is to not directly write the pod files, but to have a kind of map
file. This file contains addtional information, for example some text to end
to the start or the end of a function documention, text which should be used
instead of the auto generated one etc. There will be one entry per
function/structure, so you can leave the auto generated docs for one
function, add some additional text to another and repleace to the text
totaly for a thrid function. Also it should be possible to add new sections
of functions which are not detected by the autogeneration code.
So you never edit the resuting pod file itself, because it will be
overwritten, but only these map files. This way you save at least the copy &
paste work and have only to write the other parts of the documentation which
could not be auto generated.
I have still some work with the XS generation and generation docs will be
the next step, so it may take a few weeks until the work is done, but as
soon as I have anything to show I will post here so you can comment on it,
if this would be a reasonable way to go.
For now I can't tell you the format that these files will have, but maybe
you first continue with writing docs that can't be auto gernerated (i.e.
don't do any copy&paste work).
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: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: Automatic generation of API doc ?
Posted by Stas Bekman <st...@stason.org>.
Gerald Richter wrote:
> Hi,
>
> as some of you have noticed I currently working on mod_perl's XS generation
> system. One thing I have done is to replace C::Scan with an parser based on
> Parse::RecDescend. One benefit of this is, that it is very easy to extent
> what is parsed. So additionaly to the function and structures I currently
> also extract the comments that belongs to these functions and structures and
> lot of these comments contains the Aapache API documention in a special
> format to create the documention files from them. So why don't we use these
> comments to auto generate the pod files from them. The result has of course
> to be reviewed manualy and corrections have to made, to adopt it to the Perl
> interface, but this could be done in a similar way like it is done for the
> XS code, by having some sort of map files, which contains additional docs or
> changes on a function to function basis. That would saves a lot of
> documention handwriting.
Hi Gerald.
I've posted a question about this issue a while ago, but received no answer.
Your proposal is almost perfect. The only flaw it has is that once you
do manual adjustments you cannot use the automatic retrieval anymore,
since it'll overwrite your manual changes. You do address this issue,
but I don't think it can work with free non-structured text. Or can it?
This kind of tool will be very useful for completed, stable .h files, to
save a lot of time generating initial documentation. However currently
httpd .h files still change a lot.
Please look at the APR::Table and Apache::RequestRec pods that I've
created already:
docs/src/api/mod_perl-2.0/APR/Table.pod and
docs/src/api/mod_perl-2.0/Apache/RequestRec.pod
It would be very handy to have the tool you suggest for generating
APR::Table since I had to copy-n-paste a lot from .h file. However this
is not the case with Apache/RequestRec.pod where most of the doc is
coming from nothing :)
That's said, I'm looking forward to your new doc ripper and if you have
a chance please look at the docs I've done already and tell me whether
we should change the format of functions declaration/description.
Thanks a lot!
_____________________________________________________________________
Stas Bekman JAm_pH -- Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide http://perl.apache.org/guide
mailto:stas@stason.org http://ticketmaster.com http://apacheweek.com
http://singlesheaven.com http://perl.apache.org http://perlmonth.com/
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: Automatic generation of API doc ?
Posted by Stas Bekman <st...@stason.org>.
Gerald Richter wrote:
> Hi,
>
> as some of you have noticed I currently working on mod_perl's XS generation
> system. One thing I have done is to replace C::Scan with an parser based on
> Parse::RecDescend. One benefit of this is, that it is very easy to extent
> what is parsed. So additionaly to the function and structures I currently
> also extract the comments that belongs to these functions and structures and
> lot of these comments contains the Aapache API documention in a special
> format to create the documention files from them. So why don't we use these
> comments to auto generate the pod files from them. The result has of course
> to be reviewed manualy and corrections have to made, to adopt it to the Perl
> interface, but this could be done in a similar way like it is done for the
> XS code, by having some sort of map files, which contains additional docs or
> changes on a function to function basis. That would saves a lot of
> documention handwriting.
Hi Gerald.
I've posted a question about this issue a while ago, but received no answer.
Your proposal is almost perfect. The only flaw it has is that once you
do manual adjustments you cannot use the automatic retrieval anymore,
since it'll overwrite your manual changes. You do address this issue,
but I don't think it can work with free non-structured text. Or can it?
This kind of tool will be very useful for completed, stable .h files, to
save a lot of time generating initial documentation. However currently
httpd .h files still change a lot.
Please look at the APR::Table and Apache::RequestRec pods that I've
created already:
docs/src/api/mod_perl-2.0/APR/Table.pod and
docs/src/api/mod_perl-2.0/Apache/RequestRec.pod
It would be very handy to have the tool you suggest for generating
APR::Table since I had to copy-n-paste a lot from .h file. However this
is not the case with Apache/RequestRec.pod where most of the doc is
coming from nothing :)
That's said, I'm looking forward to your new doc ripper and if you have
a chance please look at the docs I've done already and tell me whether
we should change the format of functions declaration/description.
Thanks a lot!
_____________________________________________________________________
Stas Bekman JAm_pH -- Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide http://perl.apache.org/guide
mailto:stas@stason.org http://ticketmaster.com http://apacheweek.com
http://singlesheaven.com http://perl.apache.org http://perlmonth.com/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org