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 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 > 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.) --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
