[Dbix-class] Documentation formatting

[Brandon Black]

On 3/24/06, Andrew Ford <A.Ford at ford-mason.co.uk> wrote:
> 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.
>

The issues we've had (or will have) in this specific area are:

1) You can't sanely/easily "reference" a method's entry if you don't
use the method name as the "item" name.  We need to be able to
reference from elsewhere L<DBIx::Class::Schema/compose_namespace>, for
example.

2) Our argument syntax is often fairly complex with lots of optional
things, or arguments that can be many things (a hashref or an arrayref
in the same place, for example).  This stuff is intended interface,
and should be docced there, but it's kinda hard to provide a single
reasonable pseudo-code line that can show it all.

Perhaps:

    =item method

    =over 4

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

    =item Arguments:

    =item Returns:

    =back


-- Brandon