[Dbix-class] Documentation formatting

[Andrew Ford]

Justin Guenther wrote:
> Hello all,
>
> I just committed to trunk some changes with the formatting of
> arguments/return values in method documentation. As agreed on #dbix-class,
> the new format is:
>
> =over 4
>
> =item Arguments: (...)
>
> =item Returns: (...)
>
> =back
>
> I thought I'd give everyone a heads-up on this. I've made some other general
> formatting changes for clarity/readability's sake, and I'll be continuing to
> add args/return values documentation to everything. I'll be changing then
> committing one file at a time, so if anyone else wants to help me out feel
> free.
>
>   

A couple of general points on the documentation:

1. the indent for verbatim text is in many cases too small.  For example 
in the Manual/Example.pod file uses an indent of only one space.  When 
formatted through groff and printed out this results in a typeset indent 
of less than 2mm, which is very hard to read.  The spacing is also used 
literally when man pages are displayed in Emacs.  I would suggest a 
standard indent in the POD of 4 spaces -- it also makes reading the raw 
POD easier than indents of just one or two spaces.

2. I would avoid the use of =head3 wherever possible as in pages printed 
through groff these come out as lines set in italic at the sames size as 
the body text (but visually actually lighter and more invisible than the 
body text).  Often one can reduce the number of levels by promoting the 
=head2s to =head1s, so for example "=head2 Installation" in the 
Example.pod becomes "=head1 Installation".  Editorially there is no 
reason why everything needs to go into the Description section (in 
particular for the DBIx::Class::Manual::*.pod files), and the level 1 
headings stand out much more than the lower level headings.

3. With regards the method signatures I prefer pseudo-code.  It is what 
most Perl modules use and visually it is easier to parse than a more 
formal Arguments/Returns layout.  Of course one could have both, e.g.:

    =item $rc = $obj->method($arg1, $arg2)

    =over 4

    =item Arguments:

    =item Returns:

    =back


The problem is that headings like for example "source" (in the 
DBIx::Class::Schema page) do not to my mind leap out as documentation of 
the named method.  I would prefer to see the formatted documentation for 
a method looking something like this:

    $source = $schema->source($name)
        Returns the result source for the registered name.



BTW I had also thought about throwing together a quick reference card 
for DBIx::Class for refcards.com.

Regards
Andrew

-- 
Andrew Ford,  Director    Pauntley Prints / Ford & Mason Ltd            
A.Ford at ford-mason.co.uk   South Wing Compton House                      
pauntley-prints.co.uk     Compton Green, Redmarley  Tel: +44 1531 829900
ford-mason.co.uk          Gloucester GL19 3JB       Fax: +44 1531 829901
refcards.com cronolog.org Great Britain          Mobile: +44 7785 258278