Gerald Richter wrote:
>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:"
I have already started using something like the following: http://perl.apache.org/release/docs/2.0/api/mod_perl-2.0/APR/Table.html as I said I'm not happy with it, just trying.
So as you say we are talking about two different templates:
1. for the autogenerated docs, which keeps as much info as possible, if the info that we will not use (e.g. some C side effects, like 'const char *' vs 'char *')
2. the template for the final pod.
I don't care much about (1), whichever format is used is fine with me, as long as it's not xml.
Though we should discuss the (2), again see the URL above for some ideas.
actually we have only 2 types of arguments:
param return
so it shouldn't be a problem. I also had 'remark' in the APR::Table doc, but this can probably go into the body of the description of the method.
Is that enough?
__________________________________________________________________ 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]
