You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs-dev@perl.apache.org by Gerald Richter <ri...@ecos.de> on 2002/08/01 08:57:26 UTC
Re: Template - Autogenerating XS code and Docs
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: richter@ecos.de Voice: +49 6133 925131
WWW: http://www.ecos.de Fax: +49 6133 925152
-------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: Template - Autogenerating XS code and Docs
Posted by Randy Kobes <ra...@theoryx5.uwinnipeg.ca>.
On Sat, 16 Nov 2002, Stas Bekman wrote:
> What's the status of the API docs autogeneration? let's get
> this thing done.
I couldn't find, from earlier messages, what format was decided
for the skelton pod to be generated. From the pdd file, it
was relatively straightforward to generate pod such as
=head1 MODULE_NAME
=head1 METHODS
=over
=item method_name
description
argument list (or code listing)
return value, if any
=back
Is this basically what was in mind? And would this be in a
separate pod file, or within the associated .pm file?
--
best regards,
randy
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: Template - Autogenerating XS code and Docs
Posted by Stas Bekman <st...@stason.org>.
What's the status of the API docs autogeneration? let's get this thing done.
_____________________________________________________________________
Stas Bekman JAm_pH -- Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide http://perl.apache.org/guide
mailto:stas@stason.org http://ticketmaster.com http://apacheweek.com
http://singlesheaven.com http://perl.apache.org http://perlmonth.com/
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: Template - Autogenerating XS code and Docs
Posted by Gerald Richter <ri...@ecos.de>.
Hi,
>
> Just to clarify on my approach. The XSBuilder class parses out alot of
> data from the header file. This data is output currently as a
Data::Dumper
> string to something referred to as a PPD file.
>
> Currently I just using that output, and that only as to drive the POD
> generation. If the PPD doesn't have it, then I'll have to modify my
> approach.
>
Do you use an extra program to do this or is your code inside of WrapXS.pm?
>
> 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.
>
Yes (if you mean the class of the first argument)
>
> 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 like the idea of writing @object instead of @param
> The question of how to differentiate any C return value is similar.
>
return doesn't have a name (like Stas already pointed out)
> > 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.
This cleanup process should give as much possible feedback to the programm
writers, so we can learn from this cleanup process and hopefully automate
some more things.
>
> 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.)
>
The one you generating at the moment should be machine readable, so it gives
us the posibility to use it for other purposes as necessary.
Gerald
-------------------------------------------------------------
Gerald Richter ecos electronic communication services gmbh
Internetconnect * Webserver/-design/-datenbanken * Consulting
Post: Tulpenstrasse 5 D-55276 Dienheim b. Mainz
E-Mail: richter@ecos.de Voice: +49 6133 925131
WWW: http://www.ecos.de Fax: +49 6133 925152
-------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: Template - Autogenerating XS code and Docs
Posted by Stas Bekman <st...@stason.org>.
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
Re: Template - Autogenerating XS code and Docs
Posted by Lyle Brooks <br...@deseret.com>.
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
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: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: Template - Autogenerating XS code and Docs
Posted by Stas Bekman <st...@stason.org>.
>>>>- 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: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
Re: Template - Autogenerating XS code and Docs
Posted by Lyle Brooks <br...@deseret.com>.
Quoting Gerald Richter (richter@ecos.de):
> >
> > > Mainly it's ok. A few things are different:
> > >
> > > - The apr_ prefix gets striped in the Perl interface
That's good to know, because I don't think currently the Perl interface
name is generated directly.
> >
> > 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.
Just to clarify on my approach. The XSBuilder class parses out alot of
data from the header file. This data is output currently as a Data::Dumper
string to something referred to as a PPD file.
Currently I just using that output, and that only as to drive the POD
generation. If the PPD doesn't have it, then I'll have to modify my
approach.
>
> > > - 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. :-)
>
> >
> > >>=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?
The question of how to differentiate any C return value is similar.
> > 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.
Ok. I think the data is already stripped, so I just need to make sure
I don't add any back in as I output it.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org