Re: C function accepting/returning cstring vs. text

On 27/01/2010 9:14 PM, Ivan Sergio Borgonovo wrote:
> On Mon, 25 Jan 2010 16:36:46 -0600
> "Kevin Grittner"<Kevin.Grittner@wicourts.gov>  wrote:
>
>> Ivan Sergio Borgonovo<mail@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