httpd-apreq-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Joe Schaefer <>
Subject [PROPOSAL] docs, tables, tests (was: Re: separate pod files for Apache:: packages)
Date Mon, 19 Jul 2004 16:40:51 GMT
Joe Schaefer <> writes:


> What I'm sort-of looking for is to add one podfile for
> ::Table and one for ::Error, bringing the total pods to 5
> (the other packages are specialized enough that they probably
> don't need separate docs).  But we should somehow add links/copies
> in the installated docs so that eg
>   % man Apache::Request::Table
>   % man Apache::Cookie::Table
>   % man Apache::Upload::Table
> all point to the same documentation.

Keeping that in mind...
with the perl APIs complete, actually I think it's time 
to consider refactoring all the *::Table code into separate
modules.  The table APIs aren't 100% necessary for our perl
users, and separating them out would reduce the memory footprint
of Apache::Request, Apache::Upload, and Apache::Cookie.

So what I propose we do is

  1) add to glue/perl/docs:
     Request.pod   (replaces xsbuilder/Apache/Request/Request_pod)
     Cookie.pod    (   "           "      "  /Cookie/Cookie_pod)
     Upload.pod    (   "           "      "  /Upload/Upload_pod)
     Table.pod     (new)
     Error.pod     (new)

     We should use Test::Inline (or something similar) to extract 
     basic API tests from these pods.  I haven't given this any
     more thought, but hopefully someone can flesh out the details
     a bit to make sure this is workable.

  2) Factor the Apache::*::Table packages into separate modules.
     If we want to be nice, we could C<<require>> those modules 
     whenever Apache::Request or Apache::Cookie generates a table,
     that way users wouldn't notice the table refactoring (yes
     it's a minor performace hit, but IMO reasonable since perl's 
     TIEHASH API is really slow anyways).

  3) Have the build system transplant the /docs pods into the blib/
     directory during `make`, replicating Table.pod and Error.pod 
     as needed.

Joe Schaefer

View raw message