Re: BUG #2467: Documentation

Tom Lane wrote:
> "Rae Stiening" <stiening@stiening.com> writes:
> > Description of the "width_bucket(...)"
>
> > "return the bucket to which operand would be assigned in an equidepth
> > histogram with count buckets, an upper bound of b1, and a lower bound of
> > b2"
>
> > I believe that the lower bound is b1 and upper b2.
>
> I agree that this is a typo, but looking at the spec and the function
> code, the description seems misleading altogether.  Apparently b1 > b2
> is allowed and the computation is effectively negated then (the buckets
> are numbered in descending rather than ascending order).  So ISTM that
> just switching "lower" and "upper" in the text doesn't really get us to
> the point of adequately documenting the function.  But the description
> is already too long to fit comfortably in the table, so adding another
> sentence to cover the b1 > b2 case isn't attractive.
>
> Any ideas what to do?  Would "starting bound" and "ending bound" work,
> or just confuse people more?

I generalized the documentation section for this function.

--
  Bruce Momjian   bruce@momjian.us
  EnterpriseDB    http://www.enterprisedb.com

  + If your life is a hard drive, Christ can be your backup. +
Index: doc/src/sgml/func.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/func.sgml,v
retrieving revision 1.331
diff -c -c -r1.331 func.sgml
*** doc/src/sgml/func.sgml    21 Aug 2006 00:57:23 -0000    1.331
--- doc/src/sgml/func.sgml    22 Aug 2006 00:45:53 -0000
***************
*** 837,844 ****
         <entry><type>int</type></entry>
         <entry>return the bucket to which <parameter>operand</> would
         be assigned in an equidepth histogram with <parameter>count</>
!        buckets, an upper bound of <parameter>b1</>, and a lower bound
!        of <parameter>b2</></entry>
         <entry><literal>width_bucket(5.35, 0.024, 10.06, 5)</literal></entry>
         <entry><literal>3</literal></entry>
        </row>
--- 837,843 ----
         <entry><type>int</type></entry>
         <entry>return the bucket to which <parameter>operand</> would
         be assigned in an equidepth histogram with <parameter>count</>
!        buckets, in the range <parameter>b1</> to <parameter>b2</></entry>
         <entry><literal>width_bucket(5.35, 0.024, 10.06, 5)</literal></entry>
         <entry><literal>3</literal></entry>
        </row>