Bruce Momjian <pgman@candle.pha.pa.us> writes:
> Christopher Kings-Lynne wrote:
> >
> > Each comment is supposed to be acted upon (ie. fixed in source), then
> > deleted.
>
> Right, they are more _usage_ comments, but still I think they could be
> consolidated into manual text.
If that's "supposed" to happen it certainly hasn't been the de facto
procedure.
I think they have things partly right here though. A lot of those comments
aren't actually the kinds of things that belong in the canonical reference.
They include things like "watch out for this common error" or "here's a handy
use for this function". Often the "common error" or "handy use" are pretty
bogus but every now and then there's a genuinely useful one.
These kinds of things would just clutter up a reference. A reference should
just state unambiguously this function does XYZ and give examples that help
explain XYZ.
The PHP Docs do have a bit of a problem in that often the comments include
things like "In case X, what happens is Y" which really ought to be covered by
the canonical reference. That's a problem.
--
greg