Peter Eisentraut wrote:
> Just to add a particular point, in addition to Vince's excellent general
> points, as the one who was last to update the function documentation:
> The reason that there's no "detailed" documentation is that there are no
> details. How much can you write about round(), avg(), or current_user?
Usage, history, syntax, a few examples of common use (in actual code), error
messages that may result, times to avoid it, workarounds if it fails to do
what you want and similar ways of accomplishing the same thing, etc.....
Quite a bit, actually.
For example, here's what goes into the PHP round() entry:
http://www.php.net/manual/function.round.php
The inital documentation *is* slim. But the user-added notes (which is
really what makes the php-docs work well) add to the information in a
fast, easy to use, manner, without anyone having to learn docbook,
XML, and Jade (which is what the main PHP docs are written in.).
The same feature exists on the mySQL site:
http://www.mysql.com/documentation/mysql/commented/manual.php?section=Mathematical_functions
But it's used less. They have better examples for round(), however.
Now, compare that to:
a) finding the function in the online pg docs, (what's up with that slow search?)
http://www.postgresql.org/docs/user/x2591.htm
http://www.postgresql.org/docs/postgres/x2595.htm
b) once you find it, can you add to it?
c) Are there several examples of usage?
d) Can a newbie grasp usage, or see bare-bones examples?
There's lots of details that the new users find interesting. In the php
project, some seasoned developers use a reduced version of the manual,
no notes, because they don't need it. But a newbie, staring at something
for the first time, is more than happy to see long descriptions, long
notes, etc.
The source to do this kind of thing _in_ PHP is available from their CVS,
if it's a good idea for pgsql. However, it does use a mySQL backend,
so it would need some porting. :-)
-Ronabop
--
Personal: ron@opus1.com, 520-326-6109, http://www.opus1.com/ron/
Work: rchmara@pnsinc.com, 520-546-8993, http://www.pnsinc.com/
The opinions expressed in this email are not neccesarrily those of myself,
my employers, or any of the other little voices in my head.
