[Fwd: Conflicting mod_perl 2 documentation -- no print() method in Apache2::RequestRec]

[David Booth <da...@dbooth.org>]

Stas Bekman suggested that I forward this issue to this list . . . .

-------- Forwarded Message --------
From: David Booth <da...@dbooth.org>

This section of the mod_perl 2 User Guide:
http://perl.apache.org/docs/2.0/user/handlers/intro.html#What_are_Handlers_
shows a simple handler subroutine that will be called with an
Apache2::RequestRec object $r.  It includes the following statement that
calls a print() method:
[[
  $r->print("Now is: " . scalar(localtime) . "\n");
]]
But there is no print() method defined in Apache2::RequestRec, and there
is no indication that Apache2::RequestRec inherits from any other class:
http://search.cpan.org/~phred/mod_perl-2.0.5/docs/api/Apache2/RequestRec.pod

After wasting a couple of hours trying to figure this out, I noticed in
http://search.cpan.org/~phred/mod_perl-2.0.5/docs/api/Apache2/RequestRec.pod#output_filters
a bad link from "$r->print()" to
http://search.cpan.org/perldoc?docs%3A%3A2.0%3A%3Aapi%3A%3AApache2%3A%3ARequestIO#C_print_
which attempted to point to the Apache2::RequestIO documentation, and
that documentation does indeed list a print() method:
http://perl.apache.org/docs/2.0/api/Apache2/RequestIO.html#C_print_

Since Apache2::RequestIO extends Apache2::RequestRec, this seems to
suggest that the handler is actually called with an Apache2::RequestIO
object -- *not* merely an Apache2::RequestRec object.

If this is indeed correct, it would be very helpful if the documentation
at
http://perl.apache.org/docs/2.0/user/handlers/intro.html
were updated with this correction.

Thanks!


-- 
David Booth, Ph.D.
http://dbooth.org/

Opinions expressed herein are those of the author and do not necessarily
reflect those of his employer.