Message-ID: <47656DC3.5080700@commandprompt.com>
Date: Sun, 16 Dec 2007 10:26:11 -0800
From: "Joshua D. Drake" <jd@commandprompt.com>
Organization: Command Prompt, Inc.
User-Agent: Thunderbird 1.5.0.13 (Windows/20070809)
MIME-Version: 1.0
To: Tom Lane <tgl@sss.pgh.pa.us>
CC: Simon Riggs <simon@2ndquadrant.com>, Bruce Momjian <bruce@momjian.us>,
	pgsql-docs@postgresql.org
Subject: Re: Plug in docs
References: <200712160812.lBG8C5x15519@momjian.us>
	<47654B3A.7030206@commandprompt.com>
	<1197826806.12912.37.camel@ebony.site>
	<27293.1197827992@sss.pgh.pa.us>
In-Reply-To: <27293.1197827992@sss.pgh.pa.us>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

Tom Lane wrote:
> 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.

No it is not rooted in closed-source documentation practices. It is 
rooted is Professional documentation practices.

> 
> 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.)

I believe Simon's point is not invalidated by this email. If anything it 
reinforces it. We are not looking for War and Peace, we are looking for 
overview.

An overview can be as simple as discussing in broad strokes what the 
each API is for, the current function set and points to where in the 
code to look for further information.

Sincerely,

Joshua D. Drake