[wp-hackers] Inline documentation

[Rich Bowen]

David House 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).

This approach assumes that folks are *only* interested in the docs when
they are reading the code, and not focused on the HTML output. We seem
to be rather dual-personality on this. If we're wanting to produce a
useful, searchable, complete web-based document, then all functions must
be documented. If we're interested in having documentation in the code
that can be easily read by people looking at the source code, then we
can omit some functions, but there's no use using @param syntax, because
we don't care about the HTML output.

We should pick one approach and do it well, not do a semi-assed
implementation of both.

-- 
Rich Bowen
rbowen at rcbowen.com