Received: from maia.hub.org (maia-5.hub.org [200.46.204.29]) by mail.postgresql.org (Postfix) with ESMTP id 1F2C8133616B for ; Thu, 14 Oct 2010 20:15:54 -0300 (ADT) Received: from mail.postgresql.org ([200.46.204.86]) by maia.hub.org (mx1.hub.org [200.46.204.29]) (amavisd-maia, port 10024) with ESMTP id 25594-09 for ; Thu, 14 Oct 2010 23:15:48 +0000 (UTC) X-Greylist: from auto-whitelisted by SQLgrey-1.7.6 Received: from sss.pgh.pa.us (sss.pgh.pa.us [66.207.139.130]) by mail.postgresql.org (Postfix) with ESMTP id 34AC21335B36 for ; Thu, 14 Oct 2010 20:15:46 -0300 (ADT) Received: from sss2.sss.pgh.pa.us (tgl@localhost [127.0.0.1]) by sss.pgh.pa.us (8.14.2/8.14.2) with ESMTP id o9ENFh5h006842; Thu, 14 Oct 2010 19:15:44 -0400 (EDT) To: Robert Haas cc: Peter Eisentraut , Josh Kupershmidt , pgsql-docs@postgresql.org Subject: Re: Documenting removal of nonnullvalue() and friends In-reply-to: References: <1287064806.9532.5.camel@vanquo.pezone.net> <5718.1287094063@sss.pgh.pa.us> Comments: In-reply-to Robert Haas message dated "Thu, 14 Oct 2010 19:04:56 -0400" Date: Thu, 14 Oct 2010 19:15:43 -0400 Message-ID: <6841.1287098143@sss.pgh.pa.us> From: Tom Lane X-Virus-Scanned: Maia Mailguard 1.0.1 X-Spam-Status: No, hits=-1.91 tagged_above=-5 required=5 tests=BAYES_00=-1.9, T_RP_MATCHES_RCVD=-0.01 X-Spam-Level: X-Archive-Number: 201010/35 X-Sequence-Number: 6176 Robert Haas writes: > On Thu, Oct 14, 2010 at 6:07 PM, Tom Lane wrote: >> They should assume the lack of documentation is intentional.  Six or >> seven years ago your argument might have held some water, but we've >> been quite rigorous about requiring externally-visible features to be >> documented from the get-go. > That just doesn't match my experience. We goof. People find it. Sure, there are bugs of that sort, just like we have bugs of many other sorts. When people find them, we fix them. But the general principle is that functions and operators that are meant to be used directly from SQL are shown in the SGML documentation; and those that aren't, aren't. There are probably upwards of a thousand entries in pg_proc that are not, and never were, meant to be directly invoked from SQL. (In particular, with 706 entries in pg_operator, there are presumably about 700 functions underlying operators; and then you've got functions underlying aggregates, index AM support functions, selectivity estimation functions, text search support functions, foreign data wrapper functions, yadda yadda.) It is not sane to propose documenting those individually, not only from the standpoint of docs bloat but because documenting them would encourage people to call them, which is exactly not the result we want. regards, tom lane