stas at stason
Jul 10, 2003, 8:14 PM
Post #2 of 6
(1545 views)
Permalink
|
Jack Nerad wrote:
> 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:stas [at] stason http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe [at] perl
For additional commands, e-mail: docs-dev-help [at] perl
|
