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:[EMAIL PROTECTED] http://ticketmaster.com http://apacheweek.com http://singlesheaven.com http://perl.apache.org http://perlmonth.com/ --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
