Quoting Stas Bekman ([EMAIL PROTECTED]):
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.
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.
An example...
From apr_tables.h
/** * Get the value associated with a given key from the table. After this call, * The data is still in the table * @param t The table to search for the key * @param key The key to search for * @return The value associated with the key */ APR_DECLARE(const char *) apr_table_get(const apr_table_t *t, const char *key);
That would translate into Perl as
$val = $t->table_get($key);
$val is the return argument. $t is the object, and $key is a parameter.
In the pod template we have
=item @param: $a
=item @return: $foo
I just wanted to know if we wanted to list $t as
=item @param: $t
or something like that would designate it as an object like
=item @object: $t
Well, you can only intelligently guess about it being an object. I think saying @return is just fine.
Also, while I'm on the subject. Notice that this stuff is derived from
C function prototypes. As such, there is no named return value. $t and
$key can be derived from the prototype, but not so for the return value.
In the previous example I just made up $val.
Any suggestions?
Return value -> Variable
void "Leave Blank" one value -> $foo multiple values -> @foo
just call it $return and we manually will rename it where it's applicable.
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.
Understood. When you discussed generating the documentation in stages, I wasn't sure whether the output of this current stage would feed into more automated phases (in which case, you'd be more concerned about preserving context), or all remaining phases would be manual (in which case, a human can deduce the context so it becomes less of an issue.)
I guess we will know more as we polish the system. Let's get the basic thing working and then tune as we go.
__________________________________________________________________ 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]
