I CC the docs-dev, in case anybody want to join the discussion. > > >>>>2) Do we have "one" example that has been done by hand to serve as a > >>> > >>>guide? > >>> > >>>No > > Actually Yes, see: > http://perl.apache.org/docs/2.0/api/mod_perl-2.0/APR/Table.pod.orig > > there are more manually crafted API docs here: > http://perl.apache.org/docs/2.0/api/index.html > > but disregard them for now structure-wise, use them to get the idea on > how things should look in general. > > > Mainly it's ok. A few things are different: > > > > - The apr_ prefix gets striped in the Perl interface > > so does ap_, and sometimes its even more when the PACKAGE=guess, see how > apr_get_remote_host() becomes remote_host(). Gerald, I think it's not > enough to parse docs. You must really apply the same heuristics you > apply for creating the XS code in WrapXS, otherwise what's the point of > using WrapXS in first place for parsing docs? The logic shouldn't be > duplicated. If you get the XS right, the docs should get it right too! >
Yes of course. That's excatly what we do, but WrapXS gives so much informations and Lyle is about to figure out which are the correct one to use. So I should have said more clearly: The prefix has to be striped, i.e. use the Perl name that WrapXS provides not the C name. > > - These are method calls > > > > Stas, in the AUTOGENERATION documents the example shows a function, but I > > think in this case we have methods. What do you think? > > I don't know how to handle these generically, since some functions > become methods in perl others don't. Do we have any solid heuristics for > figuring that out? > > The simplest heuristics to start with would be to check whether the > first argument is request_rec, connection_rec, apr_pool_t, etc and turn > these into methods. The rest keep as functions. > I think basicly we should look at the first argument, if it's an object we write it as method, otherwise it will become a function. We may add some hints to the map files in case that becomes necessary. > > >>=head2 @func: apr_table_set() > >> > >> apr_table_set($t, $key, $val) > >> > > > > > > # write as > > > > $t -> table_set ($key, $val) > > yes, but no spaces please. Sorry, I always prefer spaces in my code, but of course the output should conform to the style of the rest of the mod_perl docs. > This is not how we write docs, should be: > > $t->table_set($key, $val); > > notice ';' > > [...] > > >>=item @return: > >> > >> copy of the table passed in > ^^^ > make sure to strip all leading spaces, e.g. in the above case. Since > otherwise it won't be rendered as text. > > Gerald ------------------------------------------------------------- Gerald Richter ecos electronic communication services gmbh Internetconnect * Webserver/-design/-datenbanken * Consulting Post: Tulpenstrasse 5 D-55276 Dienheim b. Mainz E-Mail: [EMAIL PROTECTED] Voice: +49 6133 925131 WWW: http://www.ecos.de Fax: +49 6133 925152 ------------------------------------------------------------- --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
