perl-modperl mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stas Bekman <s...@stason.org>
Subject Re: [mp2] Documentation - newbie questions
Date Mon, 12 Jan 2004 09:05:24 GMT
semuel wrote:
> From: Stas Bekman 
> Sent: Saturday, January 10, 2004 10:52 PM
>  
> 
>>>2. In the handlers lists, please include the name of the object that the
>>>handler is getting as parameter. 
>>
>>Which lists you are talking about, please give us the direct URL.
> 
> 
> URL: http://perl.apache.org/docs/2.0/user/handlers/http.html
> At the beginning of every handler, there is a "$r=shift" line.
> And what is missing is an "$r is ..." comment.
> Like in the response handler. Like in every other.

OK, instead of repeating it in every handler I've added a skeleton section:
http://perl.apache.org/docs/2.0/user/handlers/http.html#HTTP_Request_Handler_Skeleton

>>>That is because I looked, and couldn't decide whether
>>>PerlResponseHandler is
>>>getting Apache::RequestRec or Apache::RequestIO.
>>
>>There is no Apache::RequestIO object, there is only Apache::RequestRec.
>>Apache::RequestIO is a class that contains some methods operating on 
>>Apache::RequestRec, and which you need to load in before you can use them.
> 
> 
> Oh. You mean that RequestIO adds the content_type and the print functions to
> the $r object, that is RequestRec? Interesting. 
> The $r->print syntax confused me. Ok.

Yes. Please check out this helper module:
http://perl.apache.org/docs/2.0/api/ModPerl/MethodLookup.html
It will answer most of your questions w/o any need for documentation.

> Can you please add a paragraph in the RequestRec documentation that says:
> 
> "This class represent the request arrived from the browser, and the response
> that your program is about to send. Other classes operate on this object,
> and if you can not find a method, try looking at them:
> ... insert here the list ...
> For example, Apache::RequestIO provide the ability to write a response,
> using a "content_type" function, that is activated using:
> $r->content_type('plain/html');"
> 
> And in the classes please add:
> "This class provides additional functionality to the Apache::RequestRec
> object. The syntax for using the functions is:
> $r-><relevant example function name>(<relevant parameters>)
> Where $r is an Apache::RequestRec object."

Good suggestions, but please hold on on it and remind me to add it later. I'll 
try to autogenerate the missing pod pages first and then you and others can 
help to polish them. Thanks.

>>>3. Apache::RequestIO does not exist it the documentation. (at the line 
>>>in 1)
>>
>>what's (at the line in 1)?
> 
> 
> Oops. That was suppose to be "at the link in 1", namely:
> http://perl.apache.org/docs/2.0/api/index.html
> the RequestIO does not exist there.

That's correct. It doesn't exist. Yet.

>>Yes, there are many missing and incomplete manpages. Please send patches.
> 
> If I knew enough to correct your man page, I would not have asked these
> (that I'm sure that they are) stupid questions. 
> But I don't. all I can do is to point on something and to say, what did you
> mean there? 

Agreed. We have very few resources and we are trying to deal with completing 
the mod_perl 2.0 code and fixing bugs as a first priority, the docs are 
usually added when we add new features. We need more people to learn the API 
and help complete the manpages.

> Well, while I'm around, here are some more:
> 4. The Apache package itself, doesn't have place in the API page. (same
> page) but it does exist, as can be seen at:
> http://perl.apache.org/docs/2.0/user/handlers/http.html#PerlHeaderParserHand
> ler
> (where it use the Apache::DECLINED and Apache::method_register.

The Apache module doesn't really exist in mp2, it's spread all over other 
modules. So each method will reside in the manpage of the module it leaves in. 
We will probably add an empty Apache manpage which will simply list those 
functions and methods and point to the relevant manpages for further 
information. Again please remind me to add it if I forget.

> 5. Apache::Connection, APR::UUID, APR::Pool doesn't appear in the API page.
> (http://perl.apache.org/docs/2.0/api/index.html)

Just to give you an idea, about 70 other manpages are missing. There are more 
than 80 classes in mod_perl 2.0 and some 400 methods. Let me see if I can 
autogenerate those, so we can start filling in the missing gaps.

Of course we should first complete the manpages that deal with HTTP handlers 
as these are the most important for those moving to mp2 from mp1.

__________________________________________________________________
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


-- 
Reporting bugs: http://perl.apache.org/bugs/
Mail list info: http://perl.apache.org/maillist/modperl.html


Mime
View raw message