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 ---------------------------(end of broadcast)--------------------------- TIP 9: the planner will ignore your desire to choose an index scan if your joining column's datatypes do not match