You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@perl.apache.org by Stas Bekman <st...@stason.org> on 2004/05/08 18:36:55 UTC
[mp2] 2.0 API
So here is a sample manpage which demonstrates how all API docs will look like:
http://perl.apache.org/docs/2.0/api/APR/Socket.html
It has two parts:
http://perl.apache.org/docs/2.0/api/APR/Socket.html#API
which is what parts of the API are scheduled to be supported for 2.0 release
and:
http://perl.apache.org/docs/2.0/api/APR/Socket.html#Unsupported_API
which explains:
"APR::Socket also provides auto-generated perl interface for a few other
methods which aren't tested at the moment and therefore their API is a subject
to change. These methods will be added later as a need arises. If you need any
of these methods please contact the mod_perl development mailing list, present
your case, showing us some sample code and we will take care of adding the new
method."
So, that's the plan - completely document/test/polish the APIs that are most
likely to be used for 2.0 release. Other, least likely to be used, methods can
be added post 2.0 as a need arises. This will allows us to deliver 2.0 much
sooner, than if we have tried to cover them all.
The new file modperl-2.0/todo/api_status is the map where we are with the API
completion. For manpages that are completed for 2.0 it lists those methods
that will be supported later, so it's easy to spot them.
Your comments are very welcome.
--
__________________________________________________________________
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: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: [mp2] 2.0 API
Posted by Stas Bekman <st...@stason.org>.
Tom Schindl wrote:
> Ok. I see your point and that's why I'd vote for your second suggestion:
>
> $socket->recv:
> * obj: $socket
> * arg1: $len
and so it'll be. Thanks for the feedback, Tom.
--
__________________________________________________________________
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: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: [mp2] 2.0 API
Posted by Tom Schindl <to...@bestsolution.at>.
Stas Bekman wrote:
> Tom Schindl wrote:
>
>> Stas Bekman wrote:
>>
>>> Tom Schindl wrote:
[...]
>> Creating API-documentation like java has one is very common and the
>> same is true for UML where one does not add an arg0: obj because it's
>> implied in Object Oriented Contexts.
>>
>> Besides that. I've already created once a UML Documentation of
>> mod_perl-1+AxKit and I've already a AxKit-Plugin to render
>> UML-Documentation-Files encoded into XMI (a XML-Standard-Format for
>> UML-Diagramms).
>
>
> Yes, but many of mod_perl users aren't OO-savvy, so we want things to be
> as clear as possible, w/o relying on anything that could imply to those
> with OO background.
>
> Besides, in Java everything is OO, not so in mod_perl. We have class
> functions and class methods, in addition to normal methods.
>
Ok. I see your point and that's why I'd vote for your second suggestion:
$socket->recv:
* obj: $socket
* arg1: $len
>> I've read somewhere that you generated this documenation
>> automagically, how did you do that?
>
>
> Gerald Richter further extended ExtUtils::WrapXS originally written by
> Doug, to also pick the C source doxygen comments and convert them into
> pod (besides many other changes). See ExtUtils::XSBuilder on CPAN.
>
Good to know, thanks.
Tom
--
b e s t s o l u t i o n . a t EDV Systemhaus GmbH
------------------------------------------------------------------------
tom schindl leiter softwareentwicklung mobile ++43 664 3145958
------------------------------------------------------------------------
eduard-bodem-gasse 8/3 A-6020 innsbruck fax ++43 512 935833
http://www.bestsolution.at phone ++43 512 935834
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: [mp2] 2.0 API
Posted by Stas Bekman <st...@stason.org>.
Tom Schindl wrote:
> Stas Bekman wrote:
>
>> Tom Schindl wrote:
>> [...]
>>
>>>> It doesn't matter to me. If you prefer to have:
>>>>
>>>> * obj: $socket
>>>> * arg1: $len
>>>>
>>>
>>> I'd also prefer to have it this way. How does this look like for
>>> static methods?
>>>
>>> * class: APR::SOCKET
>>> * arg1: $len
>>
>>
>>
>> You mean for something like:
>>
>> Apache->warn(@msg);
>>
>> you suggest to have:
>>
>> class: Apache
>> arg1: @msg
>>
>> correct? Though it can be $r->warn(@msg) just as well. (Please
>> disregard for a moment that Apache::Log is a big mess, which we need
>> to rectify). Another example would be Apache->request().
>>
>
> Static implies that you can also call it as an instance method, doesn't it?
Usually, yes. But we normally refer to those as class methods I believe.
>>> Why could you not leave the obj/class. You would not state the
>>> obj/class for any other object oriented language like e.g. java, when
>>> using objects this is implied, isn't it? Normally one only marks
>>> methods to be static/instance and private/protected/public.
>>
>>
>>
>> Sorry, I'm not following you here, Tom. What are you suggesting again?
>>
>
> Well when looking at e.g. Java-API-Doc you'll never see class/obj and
> you'll document methods like this:
>
> package Apache
>
> * public static warn
> arg1: Array @msg ... Array of Messages
>
>
> package APR::SOCKET
> * public recv
> arg1: int $len ... length of messages
>
> Creating API-documentation like java has one is very common and the same
> is true for UML where one does not add an arg0: obj because it's implied
> in Object Oriented Contexts.
>
> Besides that. I've already created once a UML Documentation of
> mod_perl-1+AxKit and I've already a AxKit-Plugin to render
> UML-Documentation-Files encoded into XMI (a XML-Standard-Format for
> UML-Diagramms).
Yes, but many of mod_perl users aren't OO-savvy, so we want things to be as
clear as possible, w/o relying on anything that could imply to those with OO
background.
Besides, in Java everything is OO, not so in mod_perl. We have class functions
and class methods, in addition to normal methods.
> I've read somewhere that you generated this documenation automagically,
> how did you do that?
Gerald Richter further extended ExtUtils::WrapXS originally written by Doug,
to also pick the C source doxygen comments and convert them into pod (besides
many other changes). See ExtUtils::XSBuilder on CPAN.
--
__________________________________________________________________
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: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: [mp2] 2.0 API
Posted by Tom Schindl <to...@bestsolution.at>.
Stas Bekman wrote:
> Tom Schindl wrote:
> [...]
>
>>> It doesn't matter to me. If you prefer to have:
>>>
>>> * obj: $socket
>>> * arg1: $len
>>>
>>
>> I'd also prefer to have it this way. How does this look like for
>> static methods?
>>
>> * class: APR::SOCKET
>> * arg1: $len
>
>
> You mean for something like:
>
> Apache->warn(@msg);
>
> you suggest to have:
>
> class: Apache
> arg1: @msg
>
> correct? Though it can be $r->warn(@msg) just as well. (Please disregard
> for a moment that Apache::Log is a big mess, which we need to rectify).
> Another example would be Apache->request().
>
Static implies that you can also call it as an instance method, doesn't it?
>> Why could you not leave the obj/class. You would not state the
>> obj/class for any other object oriented language like e.g. java, when
>> using objects this is implied, isn't it? Normally one only marks
>> methods to be static/instance and private/protected/public.
>
>
> Sorry, I'm not following you here, Tom. What are you suggesting again?
>
Well when looking at e.g. Java-API-Doc you'll never see class/obj and
you'll document methods like this:
package Apache
* public static warn
arg1: Array @msg ... Array of Messages
package APR::SOCKET
* public recv
arg1: int $len ... length of messages
Creating API-documentation like java has one is very common and the same
is true for UML where one does not add an arg0: obj because it's implied
in Object Oriented Contexts.
Besides that. I've already created once a UML Documentation of
mod_perl-1+AxKit and I've already a AxKit-Plugin to render
UML-Documentation-Files encoded into XMI (a XML-Standard-Format for
UML-Diagramms).
I've read somewhere that you generated this documenation automagically,
how did you do that?
Tom
--
b e s t s o l u t i o n . a t EDV Systemhaus GmbH
------------------------------------------------------------------------
tom schindl leiter softwareentwicklung mobile ++43 664 3145958
------------------------------------------------------------------------
eduard-bodem-gasse 8/3 A-6020 innsbruck fax ++43 512 935833
http://www.bestsolution.at phone ++43 512 935834
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: [mp2] 2.0 API
Posted by Stas Bekman <st...@stason.org>.
Tom Schindl wrote:
[...]
>> It doesn't matter to me. If you prefer to have:
>>
>> * obj: $socket
>> * arg1: $len
>>
>
> I'd also prefer to have it this way. How does this look like for static
> methods?
>
> * class: APR::SOCKET
> * arg1: $len
You mean for something like:
Apache->warn(@msg);
you suggest to have:
class: Apache
arg1: @msg
correct? Though it can be $r->warn(@msg) just as well. (Please disregard for a
moment that Apache::Log is a big mess, which we need to rectify). Another
example would be Apache->request().
> Why could you not leave the obj/class. You would not state the obj/class
> for any other object oriented language like e.g. java, when using
> objects this is implied, isn't it? Normally one only marks methods to be
> static/instance and private/protected/public.
Sorry, I'm not following you here, Tom. What are you suggesting again?
--
__________________________________________________________________
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: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: [mp2] 2.0 API
Posted by Tom Schindl <to...@bestsolution.at>.
Stas Bekman wrote:
> Geoffrey Young wrote:
>
>>>> the only thing I find strange is arg1, which is always the object.
>>>> while ->
>>>> makes $self the first argument to the send() subroutine in the strict
>>>> perl
>>>> sense, from the user standpoint the first argument to the send()
>>>> method is
>>>> really $buf.
>>>
>>>
>>>
>>> Well, the object is really the first argument, since:
>>>
>>> $socket->recv($len);
>>>
>>> is really:
>>>
>>> APR::Socket::recv($socket, $len);
>>
>>
>>
>> yes, that's what I was saying :) my point was, though, that I would
>> expect
>> that given $socket->recv($len) users would colloquially say that $len
>> is the
>> first argument and not the second.
>
>
> sure, I'm not disagreeing with you :)
>
>>> Either way is fine, as long as we keep things consistent.
>>
>>
>>
>> yeah, I feel the same way. no biggie to me to keep it like it is,
>> especially since you're doing all the work :)
>
>
> It doesn't matter to me. If you prefer to have:
>
> * obj: $socket
> * arg1: $len
>
I'd also prefer to have it this way. How does this look like for static
methods?
* class: APR::SOCKET
* arg1: $len
Why could you not leave the obj/class. You would not state the obj/class
for any other object oriented language like e.g. java, when using
objects this is implied, isn't it? Normally one only marks methods to be
static/instance and private/protected/public.
Tom
> that's fine. I first thought to poll the users list but then changed my
> mind, I've asked for help many times without hardly anybody offering
> help, so I'll just proceed the way we developers decide is the best.
>
> BTW, if someone else here wishes to comment on the sample manpage,
> please do so asap, before I proceed with other manpages. Once started I
> would want to waste time going back and change things. There are a way
> too many methods to cover. Thanks!
>
> And did I mention that help is sought after? :)
>
--
b e s t s o l u t i o n . a t EDV Systemhaus GmbH
------------------------------------------------------------------------
tom schindl leiter softwareentwicklung mobile ++43 664 3145958
------------------------------------------------------------------------
eduard-bodem-gasse 8/3 A-6020 innsbruck fax ++43 512 935833
http://www.bestsolution.at phone ++43 512 935834
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: [mp2] 2.0 API
Posted by Stas Bekman <st...@stason.org>.
Geoffrey Young wrote:
>>>the only thing I find strange is arg1, which is always the object.
>>>while ->
>>>makes $self the first argument to the send() subroutine in the strict
>>>perl
>>>sense, from the user standpoint the first argument to the send()
>>>method is
>>>really $buf.
>>
>>
>>Well, the object is really the first argument, since:
>>
>> $socket->recv($len);
>>
>>is really:
>>
>> APR::Socket::recv($socket, $len);
>
>
> yes, that's what I was saying :) my point was, though, that I would expect
> that given $socket->recv($len) users would colloquially say that $len is the
> first argument and not the second.
sure, I'm not disagreeing with you :)
>>Either way is fine, as long as we keep things consistent.
>
>
> yeah, I feel the same way. no biggie to me to keep it like it is,
> especially since you're doing all the work :)
It doesn't matter to me. If you prefer to have:
* obj: $socket
* arg1: $len
that's fine. I first thought to poll the users list but then changed my mind,
I've asked for help many times without hardly anybody offering help, so I'll
just proceed the way we developers decide is the best.
BTW, if someone else here wishes to comment on the sample manpage, please do
so asap, before I proceed with other manpages. Once started I would want to
waste time going back and change things. There are a way too many methods to
cover. Thanks!
And did I mention that help is sought after? :)
--
__________________________________________________________________
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: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: [mp2] 2.0 API
Posted by Geoffrey Young <ge...@modperlcookbook.org>.
>> the only thing I find strange is arg1, which is always the object.
>> while ->
>> makes $self the first argument to the send() subroutine in the strict
>> perl
>> sense, from the user standpoint the first argument to the send()
>> method is
>> really $buf.
>
>
> Well, the object is really the first argument, since:
>
> $socket->recv($len);
>
> is really:
>
> APR::Socket::recv($socket, $len);
yes, that's what I was saying :) my point was, though, that I would expect
that given $socket->recv($len) users would colloquially say that $len is the
first argument and not the second.
>
> Besides, notice that the actual variable name is listed in the item and
> even the fact that it's an object, so it says:
>
> * arg1: $socket (APR::Socket object)
> * arg2: $len (number)
yeah, that's what I found confusing. well, not confusing to me personally,
of course, but potentially confusing for users.
>
> e.g. we could say:
>
> * obj: $socket
> * arg1: $len
that might be better.
> but once we do that someone might just as well argue that it's confusing
> to have $len denoted as arg1.
I suppose, but only if they wanted to cause trouble :)
>
> Either way is fine, as long as we keep things consistent.
yeah, I feel the same way. no biggie to me to keep it like it is,
especially since you're doing all the work :)
--Geoff
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: [mp2] 2.0 API
Posted by Stas Bekman <st...@stason.org>.
Geoffrey Young wrote:
>>That's exactly why I'm asking here. Please commit a better wording, since
>>it's going to appear on all other manpages with similar issues.
>
>
> will do
Excellent!
>>Besides the issue with unsupported methods, the rest looks good to you?
>>
>
>
> yeah, it looks great!
Thanks.
> the only thing I find strange is arg1, which is always the object. while ->
> makes $self the first argument to the send() subroutine in the strict perl
> sense, from the user standpoint the first argument to the send() method is
> really $buf.
Well, the object is really the first argument, since:
$socket->recv($len);
is really:
APR::Socket::recv($socket, $len);
Besides, notice that the actual variable name is listed in the item and even
the fact that it's an object, so it says:
* arg1: $socket (APR::Socket object)
* arg2: $len (number)
So the enumeration is really just an added value. May be we can simply drop
the numbers...
That's my thinking so far.
However if you think that there is a better way to represent things, please
suggest so.
e.g. we could say:
* obj: $socket
* arg1: $len
but once we do that someone might just as well argue that it's confusing to
have $len denoted as arg1.
Either way is fine, as long as we keep things consistent.
> so, if possible, I'd prefer to see the docs reflect that. but
> I realize lots of this is probably autogenerated so it might not be that
> simple.
That's not a problem. All autogenerated methods need manual work anywhere, and
many methods weren't picked by Gerald's tool at all. So I have to go through
.xs files and make sure that none are missed.
--
__________________________________________________________________
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: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: [mp2] 2.0 API
Posted by Geoffrey Young <ge...@modperlcookbook.org>.
> That's exactly why I'm asking here. Please commit a better wording, since
> it's going to appear on all other manpages with similar issues.
will do
> Yes, 'there are not only not documented and tested', but 'they are also
> subject to change', since we haven't tested them we can't know whether
> the autogenerated API is good or working at all. Not all autogenerated
> methods can really work without some additional massaging of the in/out
> args.
cool.
>
> Besides the issue with unsupported methods, the rest looks good to you?
>
yeah, it looks great!
the only thing I find strange is arg1, which is always the object. while ->
makes $self the first argument to the send() subroutine in the strict perl
sense, from the user standpoint the first argument to the send() method is
really $buf. so, if possible, I'd prefer to see the docs reflect that. but
I realize lots of this is probably autogenerated so it might not be that simple.
--Geoff
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: [mp2] 2.0 API
Posted by Stas Bekman <st...@stason.org>.
Geoffrey Young wrote:
>>"APR::Socket also provides auto-generated perl interface for a few other
>>methods which aren't tested at the moment and therefore their API is a
>>subject to change. These methods will be added later as a need arises.
>
>
> those two statements don't really jive. hopefully, you mean to say "these
> methods will be made official and documented as a need arises." that is,
> the methods are there and available for use since they are currently
> autogenerated, we just haven't committed to them.
That's exactly why I'm asking here. Please commit a better wording, since it's
going to appear on all other manpages with similar issues. I want us to devise
one manpage that we are happy with, so that we can use it as a template for
the other 50 or so man pages.
>>So, that's the plan - completely document/test/polish the APIs that are
>>most likely to be used for 2.0 release. Other, least likely to be used,
>>methods can be added post 2.0 as a need arises. This will allows us to
>>deliver 2.0 much sooner, than if we have tried to cover them all.
>
>
> so long as "added post 2.0" release means that they are available for use,
> just not documented or tested, which is the middle ground I thought we had
> found last we discussed this.
Yes, 'there are not only not documented and tested', but 'they are also
subject to change', since we haven't tested them we can't know whether the
autogenerated API is good or working at all. Not all autogenerated methods can
really work without some additional massaging of the in/out args.
Besides the issue with unsupported methods, the rest looks good to you?
--
__________________________________________________________________
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: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: [mp2] 2.0 API
Posted by Geoffrey Young <ge...@modperlcookbook.org>.
> "APR::Socket also provides auto-generated perl interface for a few other
> methods which aren't tested at the moment and therefore their API is a
> subject to change. These methods will be added later as a need arises.
those two statements don't really jive. hopefully, you mean to say "these
methods will be made official and documented as a need arises." that is,
the methods are there and available for use since they are currently
autogenerated, we just haven't committed to them.
> So, that's the plan - completely document/test/polish the APIs that are
> most likely to be used for 2.0 release. Other, least likely to be used,
> methods can be added post 2.0 as a need arises. This will allows us to
> deliver 2.0 much sooner, than if we have tried to cover them all.
so long as "added post 2.0" release means that they are available for use,
just not documented or tested, which is the middle ground I thought we had
found last we discussed this.
--Geoff
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org