At 14:17 12.06.2002, Stas Bekman wrote:
Per Einar Ellefsen wrote:
At 12:04 12.06.2002, Gerald Richter - ecos gmbh wrote:
That's only a rought idea, maybe somebodyelse has another idea how to handle
this?
Might not be the best idea, but what I was thinking about was making it template-like, having the auto-fetches things inserted in the manual edited POD. Like.
[% ap_table_add %] <---- inserts POD with function synopsis etc.
Manually added notes go here......
The problem is that new functions won't be picked up automatically, except if we have some special mark at the EOF where new functions can be inserted. However, I think that new functions will need to be handled manually anyway, as they need to have some order/classification that automatic generation can't do.
As I've explained in my reply to Gerald, I doubt it'll be possible to automatically modify docs which were manually adjusted, because we want to be able to adjust parts that were autogenerated.
Yes, I understand what you mean. After some thought, here's what I think: we build some tool to auto-generate docs the first time around. Like that we can get instant documentation now, without writing it ourselves. Then, we just take those, and restructure them to they become manually edited. That'll need to be done, but atleast we'll have something upfront.
That's exactly what I was suggesting. Plus we continue to use this script to generate fresh sets of docs everytime we update the API. Then we make a diff with the previous autogenerated set (which we have wisely stored away) and voila we get only the changes that need to be manually integrated to the real docs.
Furthermore, I think my example could still beneficially be used to insert things like function sysopsis, which aren't dependent on writing style, just on arguments etc.
That's for the template that will be used for creating the auto-docs, no?
__________________________________________________________________ Stas Bekman JAm_pH ------> Just Another mod_perl Hacker http://stason.org/ mod_perl Guide ---> http://perl.apache.org mailto:[EMAIL PROTECTED] http://use.perl.org http://apacheweek.com http://modperlbook.org http://apache.org http://ticketmaster.com
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
