Re: cvs commit: httpd-apreq-2/glue/perl/docs Cookie.pod

[Stas Bekman <st...@stason.org>]

joes@apache.org wrote:
> joes        2004/07/24 19:15:53
> 
>   Modified:    glue/perl/docs Cookie.pod
>   Log:
>   Style cleanups
>   
>   Revision  Changes    Path
>   1.5       +20 -20    httpd-apreq-2/glue/perl/docs/Cookie.pod
>   
>   Index: Cookie.pod
>   ===================================================================
>   RCS file: /home/cvs/httpd-apreq-2/glue/perl/docs/Cookie.pod,v
>   retrieving revision 1.4
>   retrieving revision 1.5
>   diff -u -r1.4 -r1.5
>   --- Cookie.pod	25 Jul 2004 00:58:50 -0000	1.4
>   +++ Cookie.pod	25 Jul 2004 02:15:53 -0000	1.5
>   @@ -46,10 +46,10 @@
>    =head1 DESCRIPTION
>    
>    
>   -The new Apache::Cookie module is based on the original 1.X versions, which mimic 
>   +The 2.X Apache::Cookie module is based on the original 1.X versions, which mimic 
>    the CGI::Cookie API.  The current version of this module includes several packages 
>    and methods which are patterned after Apache::Request, yet remain largely 
>   -backwards-compatible with the original 1.X API (see the L<PORTING> section 
>   +backwards-compatible with the original 1.X API (see the L<PORTING from 1.X> section 
>    below for known issues).
>    
>    This manpage documents the Apache::Cookie and Apache::Cookie::Jar packages.  
>   @@ -65,7 +65,7 @@
>    
>    
>    
>   -=head2 new($env, %settings)
>   +=head2 C<< new($env, %settings) >>

This style of headers will make it horribly hard to make 
cross-references. Have you considered to use a different style where you 
only write the method name in the header and list all possible calling 
styles in the body?

=head2 C<new>

   $cookie = Apache::Cookie->new($env, %settings)

...

=head2 C<cookies>

   %cookies = cookies();
   %cookies = cookies($key);

...

So an xref to the cookies entry will now be: L<cookies()|/C_cookies_> 
and not L<cookies()|/C___cookies____cookies__key____>, or whatever the 
current POD spec converts it to.

For example in modperl-2.0/docs/api/Apache/ServerUtil.pod we have:

=head2 C<dir_config>

C<$s-E<gt>dir_config()> provides an interface for the per-server
variables specified by the C<PerlSetVar> and C<PerlAddVar> directives,
and also can be manipulated via the
C<L<APR::Table|docs::2.0::api::APR::Table>> methods.

   $table  = $s->dir_config();
   $value  = $s->dir_config($key);
   @values = $s->dir_config($key);
   $s->dir_config($key, $val);

=over 4

=item obj: C<$s>
( C<L<Apache::ServerRec object|docs::2.0::api::Apache::ServerRec>> )

=item opt arg2: C<$key> ( string )

Key string

=item opt arg3: C<$val> ( string )

Value string

=item ret: ...

Depends on the passed arguments, see further discussion

=item since: 1.99_10

=back

....


-- 
__________________________________________________________________
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

Re: cvs commit: httpd-apreq-2/glue/perl/docs Cookie.pod

[Joe Schaefer <jo...@sunstarsys.com>]

Stas Bekman <st...@stason.org> writes:

[...]

> This style of headers will make it horribly hard to make
> cross-references. Have you considered to use a different style where
> you only write the method name in the header and list all possible
> calling styles in the body? 
> 
> =head2 C<new>
> 
>    $cookie = Apache::Cookie->new($env, %settings)
> 
> ...
> 
> =head2 C<cookies>
> 
>    %cookies = cookies();
>    %cookies = cookies($key);

+1, thanks for the suggestion.  I'll fix the cookie docs to use 
this format.

-- 
Joe Schaefer