[wp-hackers] Inline documentation

[Robert Deaton]

On 2/17/06, Rich Bowen <rbowen at rcbowen.com> wrote:
> 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.

I personally believe that we should stick with PHPDoc syntax with
@param and @return.

In case it wasn't clarified with the responses, here's a quick psuedo
comment that describes what they do, and how easy it is to represent
code with PHPDoc. Each @param represents one of the parameters or
arguments to the function, in order.

/**
  * Description goes here
  * @param int $number or other description
  * @param  string $some text for a link
  * @return string the final output
  **/

Its easy to understand for humans and parsers alike, and is especially
useful to the number of us who use Zend Studio for code development,
as they have beautiful tooltips automatically generated from these
comments that explains everything nicely.

--
--Robert Deaton
http://somethingunpredictable.com