On 27/01/2010 9:14 PM, Ivan Sergio Borgonovo wrote:
On Mon, 25 Jan 2010 16:36:46 -0600
"Kevin Grittner"<kevin.gritt...@wicourts.gov> wrote:
Ivan Sergio Borgonovo<m...@webthatworks.it> wrote:
The README files might be a good place to start, then browse code.
Is there a book?
The more I read the source and the few info about it, the more I
have questions that should have been answered by documenting the
function or data structure in spite of looking for some code that
use it and see if I can infer what is expecting, what should be the
best context to use it in, if there are better candidates to do the
same thing etc...
I don't code on PostgreSQL's guts, so I'm perhaps not in the best
position to speak, but:
- Documentation has a cost too, particularly a maintenance cost.
Outdated docs become misleading or downright false and can be much more
harm than good. So a reasonable balance must be struck. I'm not saying
PostgreSQL is _at_ that reasonable balance re its internal
documentation, but there is such a thing as over-documenting. Writing a
small book on each function means you have to maintain that, and that
gets painful if code is undergoing any sort of major change.
- It's easy to say "should" when you're not the one writing it.
Personally, I try to say "hey, it's cool that I have access to this
system" and "isn't it great I even have the right to modify it to do
what I want, even though the learning curve _can_ be pretty steep".
Hey, you could contribute yourself - patch some documentation into those
functions where you find that reading the source isn't clear enough, and
they really need a "see also" or "called from" comment or the like.
As it is, I'm extremely grateful for the excellent user-level/admin
oriented manual and glad to see the SPI docs too.
--
Craig Ringer
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
