[wp-hackers] Inline documentation

[Carthik Sharma]

On 2/17/06, David House <dmhouse at gmail.com> wrote:
> On 17/02/06, Owen Winkler <ringmaster at midnightcircus.com> wrote:
> > Here's (IMO) a reasonable PHPDoc comment:
> >
> > /**
> >   * returns the system time in the format specified by $type
> >   * @param type string 'mysql' | 'timestamp'
> >   * @param gmt boolean
> >   * @return mixed
> >   */
>
> As Matt has expressed his distaste for comments before really short
> functions, here's a more complicated example for list_cats()
> (attached).
>
> Issues raised by writing this:
>
> * I found four completely pointless parameters. Four! (the three
> listed as 'Doesn't seem to do anything', then $hierarchical as well)
> Here shows the benefits of documenting.
Digressing from the main topic here:
David, some of the "Doesn't seem to do anything" params (like `all`
and `optionall`) are actually supposed to do stuff , and they did,
prior to a commit that broke that functionality. I suppose that is a
bug, then.
http://comox.textdrive.com/pipermail/wp-docs/2006-January/001232.html
is where I wrote up about this recently.

> * I hope the format is to taste, I didn't bother with anything other
> than @param and @return.
> * What to do about functions that don't return anything? @return
> nothing, @return null or just no @return at all?
Why don't we use @return void ?

> * Hopefully my explanations of the parameters were clear enough.
> No-one ever has to go through that function again, they just check the
> reference at the top.
Yes, a brief description of parameters, and what they mean should be
what is necessary and sufficient. I often find myself using a phpxref
install just to figure these things out, and each time, I read the
function in question and figure out what the heck parameter X does.

Carthik.