Re: Autogenerated PODs :-)

[Stas Bekman]

Great work, Lyle and Gerald!

I've a few comments so far:

1) build: something is missing from README because xsbuilder/xs_generate.pl was looking for xsbuilder/maps and couldn't find it. I've added a symlink similar to xsbuilder/xs and then it worked. shouldn't it look for xsbuilder/xs/maps instead?

2) layout:

Here is a snippet from perldoc's output on Apache/RequestUtil.pm (indented to the right) with comments starting at /^/:

Apache::RequestUtil

To save typing would be a good idea to start the functions with:

=head1 Functions

@func: default_type()

$ret = $r->default_type()

semicolon would be nice

@param: Apache::RequestRec $r
The current request

would be nice to add the markup: C<L<Apache::RequestRec>> C<$r>, or
should this be done at the final conversion stage? It actually should
be
C<L<Apache::RequestRec|docs::2.0::api::mod_perl-2.0::Apache::RequestRec>>

@ret: PV
The default type

C struct types aren't really useful to Perl programmers, I guess this
can be converted in the final pod (e.g. PV => scalar, AV => list,...)

@since: 2.0.1

2.0.1 is an Apache version, Shouldn't this be a mod_perl version?
suppose it should say since: httpd-2.0.1, mod_perl-1.99_apr-0.9.1
whatever is appropriate?

Retrieve the document root for this server

May be put the short description first? And then full desc after the
usage?


...

In general < and > should be escaped E<lt>, E<gt> but we probably should do better in cases like: Apache/RequestIO/RequestIO.pod:

@param: Apache::RequestRec $read_policy
How the server should interpret a chunked transfer-encoding. One
of: <pre>
REQUEST_NO_BODY Send 413 error if message has any body
REQUEST_CHUNKED_ERROR Send 411 error if body without Con-
tent-Length
REQUEST_CHUNKED_DECHUNK If chunked, remove the chunks for me.
</PRE>

should probably convert <pre> by adding a separating new line and making sure that a 2 chars leading space starts every line of <pre>, including empty lines.

__________________________________________________________________
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]