Stas Bekman wrote:
[moving this discussion to the mod_perl docs list so others can contribute. Also CC'ing Lyle and Jack who has offered help with this project and probably have already gave up, trying to figure out where they could help. Hopefully this Gerald's code will provide the missing fuel]
I have started to work on XSBuilder again. The first thing I have done is to
create a module called ModPerl::PODTemplate, which contains a set of methods
which allows to easily change the format of the generated POD. I attach you
the new version, along with two files I have generated. I didn't have made
any changes in the format so far. I would like to get your feedback, on how
the output should look like, them I can implement it imediately (or of
course you can change mpbuilder/lib/ModPerl/PODTemple.pm on your own and
play with it)
But I have already provided the feedback, when you first posted it long time ago. http://mathforum.org/epigone/modperl-docs-dev/fyhahmen
Here are some more comments:
The examples look OK I suppose, I think we have already agreed to have $t->foo and not $t -> foo.
From the recent work on the docs, I think I prefer to have all the functions in =head2 to be enclosed in C<> so they look good in the TOC. Granted it makes it more cumbersome to write L<> links manually, but the end user gets better docs.
same for all variables, they should be C<>, to save us a lot of manual work.
Should description of the method come before its arguments?
things like <PRE> are HTML, not pod. see Table.pod that you have attached.
Things like PV/IV make little sense to users. Perhaps replace them with SCALAR? So we may have SCALAR, ARRAY, VOID
What are PV and IV?
PV = string IV = integer value
For more info see: http://gisle.aas.no/perl/illguts/
So for docs I think we should replace those with "string", "number", etc.
@since: 1.99 : should probably be more specific, i.e. 1.99_09
Where does that version come from?
we set it once automatically when we generate the first docs set and from then maintain it manually.
Finally, are you sure that we want to maintain this intermediary format. It's going to be a big pain. I suggest to drop the idea and go with the plain pod. We have very little human resources to work on docs, so the less we have to maintain the better.
That's fine with me.
It's fine with us end users, Gerald wanted to have an intermediate format for other reasons.
A sample function entry would look like this, as I understand it:
=head2 C<pool()>
$val = $obj->pool($newval)
please add two spaces in front of the code sections
=over 4
=item Calling Object Type: Apache::RequestRec
=item Return Value Type: APR::Pool
=item since: 1.99
Have you looked at modperl-docs/src/docs/2.0/api/AUTOGENERATION
we need to update it a bit though, but it's good enough to get the idea.
__________________________________________________________________ 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]
