perl-docs-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stas Bekman <s...@stason.org>
Subject Re: Template - Autogenerating XS code and Docs
Date Sun, 11 Aug 2002 12:37:09 GMT
Lyle Brooks wrote:
> Quoting Stas Bekman (stas@stason.org):
> 
>>>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:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org   http://ticketmaster.com


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org


Mime
View raw message