Re: [DOCS] Plug in 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 <[EMAIL PROTECTED]>http://momjian.us EnterpriseDB http://postgres.enterprisedb.com + If your life is a hard drive, Christ can be your backup. + ---(end of broadcast)--- TIP 3: Have you checked our extensive FAQ? http://www.postgresql.org/docs/faq
Re: [DOCS] Plug in 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 ---(end of broadcast)--- TIP 9: In versions below 8.0, the planner will ignore your desire to choose an index scan if your joining column's datatypes do not match
Re: [DOCS] Plug in 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 ---(end of broadcast)--- TIP 3: Have you checked our extensive FAQ? http://www.postgresql.org/docs/faq
Re: [DOCS] Plug in docs
Simon Riggs <[EMAIL PROTECTED]> 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 ---(end of broadcast)--- TIP 2: Don't 'kill -9' the postmaster
Re: [DOCS] Plug in docs
Tom Lane wrote: Simon Riggs <[EMAIL PROTECTED]> 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 ---(end of broadcast)--- TIP 6: explain analyze is your friend
