pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedPlug in docs
6+ messages / 4 participants
[nested] [flat]
* Plug in docs
@ 2007-12-05 08:40 Simon Riggs <simon@2ndquadrant.com>
0 siblings, 1 reply; 6+ messages in thread
From: Simon Riggs @ 2007-12-05 08:40 UTC (permalink / raw)
To: pgsql-docs
Looks like we need some docs on all these new plugin APIs we've
introduced in this release.
- PL/pgSQL hooks
- planner hooks
- join order hooks
Thanks,
--
Simon Riggs
2ndQuadrant http://www.2ndQuadrant.com
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: Plug in docs
@ 2007-12-16 08:12 Bruce Momjian <bruce@momjian.us>
parent: Simon Riggs <simon@2ndquadrant.com>
0 siblings, 1 reply; 6+ messages in thread
From: Bruce Momjian @ 2007-12-16 08:12 UTC (permalink / raw)
To: Simon Riggs <simon@2ndquadrant.com>; +Cc: pgsql-docs
Simon Riggs wrote:
> Looks like we need some docs on all these new plugin APIs we've
> introduced in this release.
>
> - PL/pgSQL hooks
> - planner hooks
> - join order hooks
Do we normally document these? I think these are
documented-in-the-source-code type issues.
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://postgres.enterprisedb.com
+ If your life is a hard drive, Christ can be your backup. +
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: Plug in docs
@ 2007-12-16 15:58 Joshua D. Drake <jd@commandprompt.com>
parent: Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 6+ messages in thread
From: Joshua D. Drake @ 2007-12-16 15:58 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: Simon Riggs <simon@2ndquadrant.com>; pgsql-docs
Bruce Momjian wrote:
> Simon Riggs wrote:
>> Looks like we need some docs on all these new plugin APIs we've
>> introduced in this release.
>>
>> - PL/pgSQL hooks
>> - planner hooks
>> - join order hooks
>
> Do we normally document these? 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.
Sincerely,
Joshua D. Drake
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: Plug in docs
@ 2007-12-16 17:40 Simon Riggs <simon@2ndquadrant.com>
parent: Joshua D. Drake <jd@commandprompt.com>
0 siblings, 1 reply; 6+ messages in thread
From: Simon Riggs @ 2007-12-16 17:40 UTC (permalink / raw)
To: Joshua D. Drake <jd@commandprompt.com>; +Cc: Bruce Momjian <bruce@momjian.us>; pgsql-docs
On Sun, 2007-12-16 at 07:58 -0800, Joshua D. Drake wrote:
> Bruce Momjian wrote:
> > Simon Riggs wrote:
> >> Looks like we need some docs on all these new plugin APIs we've
> >> introduced in this release.
> >>
> >> - PL/pgSQL hooks
> >> - planner hooks
> >> - join order hooks
> >
> > Do we normally document these?
I don't believe that there is a "normal" yet that applies for these.
> 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.
Doesn't need to be War and Peace, just an overview.
--
Simon Riggs
2ndQuadrant http://www.2ndQuadrant.com
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: Plug in docs
@ 2007-12-16 17:59 Tom Lane <tgl@sss.pgh.pa.us>
parent: Simon Riggs <simon@2ndquadrant.com>
0 siblings, 1 reply; 6+ messages in thread
From: Tom Lane @ 2007-12-16 17:59 UTC (permalink / raw)
To: Simon Riggs <simon@2ndquadrant.com>; +Cc: Joshua D. Drake <jd@commandprompt.com>; Bruce Momjian <bruce@momjian.us>; pgsql-docs
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
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: Plug in docs
@ 2007-12-16 18:26 Joshua D. Drake <jd@commandprompt.com>
parent: Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 0 replies; 6+ messages in thread
From: Joshua D. Drake @ 2007-12-16 18:26 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Simon Riggs <simon@2ndquadrant.com>; Bruce Momjian <bruce@momjian.us>; pgsql-docs
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
^ permalink raw reply [nested|flat] 6+ messages in thread
end of thread, other threads:[~2007-12-16 18:26 UTC | newest]
Thread overview: 6+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2007-12-05 08:40 Plug in docs Simon Riggs <simon@2ndquadrant.com>
2007-12-16 08:12 ` Bruce Momjian <bruce@momjian.us>
2007-12-16 15:58 ` Joshua D. Drake <jd@commandprompt.com>
2007-12-16 17:40 ` Simon Riggs <simon@2ndquadrant.com>
2007-12-16 17:59 ` Tom Lane <tgl@sss.pgh.pa.us>
2007-12-16 18:26 ` Joshua D. Drake <jd@commandprompt.com>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox