To: Simon Riggs <simon@2ndquadrant.com>
cc: "Joshua D. Drake" <jd@commandprompt.com>,
 Bruce Momjian <bruce@momjian.us>,
	pgsql-docs@postgresql.org
Subject: Re: Plug in docs 
In-reply-to: <1197826806.12912.37.camel@ebony.site> 
References: <200712160812.lBG8C5x15519@momjian.us>
	<47654B3A.7030206@commandprompt.com>
	<1197826806.12912.37.camel@ebony.site>
Comments: In-reply-to Simon Riggs <simon@2ndquadrant.com>
	message dated "Sun, 16 Dec 2007 17:40:06 +0000"
Date: Sun, 16 Dec 2007 12:59:52 -0500
Message-ID: <27293.1197827992@sss.pgh.pa.us>
From: Tom Lane <tgl@sss.pgh.pa.us>

Simon Riggs <simon@2ndquadrant.com> writes:
> On Sun, 2007-12-16 at 07:58 -0800, Joshua D. Drake wrote:
>> Bruce Momjian wrote:
>>> I think these are
>>> documented-in-the-source-code type issues.
>> 
>> If they are an API they need to be documented. Code is poor (even well 
>> documented code) substitute for good old fashioned docs.

> Agreed.

I don't agree --- I think the above opinion is rooted in closed-source
documentation practices where you *have to* document things without
reference to the code.  In an open-source situation the ground rules
are completely different, and we shouldn't make unnecessary work for
ourselves.

In particular, for all three of the hooks at hand, it would be out of
the question for anyone to make real use of them without a great deal
of code-reading.  There is never going to be extensive documentation
in the SGML manual of all internal planner APIs, for example, and yet
you're not going to accomplish anything very useful with either of
the planner hooks unless you understand that stuff.

Also, if you think any of these are APIs in the sense that we promise
never to change them, you're mistaken.  (Again, it's not so much the
hook itself that's the problem, as all the stuff that the hooked-in
function needs to know about.)

			regards, tom lane