- 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.
I interpret that as if the class is a package, then we treat the C function as an object method, otherwise we treat it as a Perl function.
I've seen method call examples. Can you give me a function call example. Examples always help. :-)
Lyle, you have all the examples that you need in t/, just grep for the function in question and most likely you will find it under t/.
For example any function that has request_rec as it first arg, is a method most of the time.
=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);
Now if we make the first C argument an object, what do we do with the documentation for it. Putting in along side the method parameters as just another "=item" seems confusing. Do we create a new breakout?
I think =item is just fine, because it's an argument, though a special one. Remember that:
$t->table_set($key, $val);
is really:
APR::Table::table_set($t, $key, $val);
The question of how to differentiate any C return value is similar.
What do you mean? Are you talking about things passed by a reference? I think you should be able to deduce that from the map files, since map files are used to make APIs perlish. But I don't see any examples where there is more than one value returned. I guess this is all done in the wrapping code.
I think you should just list all the arguments as arguments, and when we manually cleanup the autogenerated pages, we will fix those things. What's important is to save on writing descriptions (correctly). Reshuffling things is not a problem. We will have to scrutinize all the generated docs in any case.
__________________________________________________________________ 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]
