Horton

Thread

  1. Re: libpq documentation cleanups (repost 3)

    Bruce Momjian <bruce@momjian.us> — 2011-01-13T01:54:08Z

    Robert Haas wrote:
> On Wed, Jan 12, 2011 at 1:12 PM, Bruce Momjian <bruce@momjian.us> wrote:
> >> OK, that last part seems kind of vague. ?;-) ?Can you hack up the diff
> >> to have just the changes you think are worthwhile? ?You can just remove
> >> the parts of the diff you don't like.
> >
> > Robert, here is a unified diff, which I think it easier to review for
> > single-line documention changes.
> 
> Here are the parts that seem like improvements to me.

Applied.

I am also attaching a few more of Leslie's changes that I think are
useful.  The first clarifies a confusion Leslie had about the fact that
"return" is referencing the return value of the function and not the
value returned in the pointer.

The second change is, I think, better wording.

The third moves the "deprecated" text to the start of the function
description.  Leslie pointed out that that is how we do it for other
libpq functions, so we should move it for consistency.

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

  + It's impossible for everything to be true. +

  2. Re: libpq documentation cleanups (repost 3)

    Robert Haas <robertmhaas@gmail.com> — 2011-01-13T10:59:47Z

    On Wed, Jan 12, 2011 at 8:54 PM, Bruce Momjian <bruce@momjian.us> wrote:
> I am also attaching a few more of Leslie's changes that I think are
> useful.  The first clarifies a confusion Leslie had about the fact that
> "return" is referencing the return value of the function and not the
> value returned in the pointer.

Hmm.  Well, if that's the confusion, I don't think inserting the words
"by the function" is the right way to fix it - it certainly isn't
returned by anything else.  You could change it to say "It is also
possible for *errmsg to be NULL even when the return value is also
NULL; this indicates..."

> The second change is, I think, better wording.

OK.

> The third moves the "deprecated" text to the start of the function
> description.  Leslie pointed out that that is how we do it for other
> libpq functions, so we should move it for consistency.

That seems to me to read pretty awkwardly.  You could perhaps strike
the chunk and the whole first paragraph and simply write "PQoidStatus
is an older, deprecated version of PQoidValue.  It returns its result
as a character string rather than an Oid, and is not thread-safe." and
then cut directly to the synopsis.  That would be consistent with what
we've done elsewhere; moving just that one sentence is not.

-- 
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

  3. Re: libpq documentation cleanups (repost 3)

    Bruce Momjian <bruce@momjian.us> — 2011-01-13T17:09:09Z

    Robert Haas wrote:
> On Wed, Jan 12, 2011 at 8:54 PM, Bruce Momjian <bruce@momjian.us> wrote:
> > I am also attaching a few more of Leslie's changes that I think are
> > useful. ?The first clarifies a confusion Leslie had about the fact that
> > "return" is referencing the return value of the function and not the
> > value returned in the pointer.
> 
> Hmm.  Well, if that's the confusion, I don't think inserting the words
> "by the function" is the right way to fix it - it certainly isn't
> returned by anything else.  You could change it to say "It is also
> possible for *errmsg to be NULL even when the return value is also
> NULL; this indicates..."
> 
> > The second change is, I think, better wording.
> 
> OK.
> 
> > The third moves the "deprecated" text to the start of the function
> > description. ?Leslie pointed out that that is how we do it for other
> > libpq functions, so we should move it for consistency.
> 
> That seems to me to read pretty awkwardly.  You could perhaps strike
> the chunk and the whole first paragraph and simply write "PQoidStatus
> is an older, deprecated version of PQoidValue.  It returns its result
> as a character string rather than an Oid, and is not thread-safe." and
> then cut directly to the synopsis.  That would be consistent with what
> we've done elsewhere; moving just that one sentence is not.

OK, I have made the adjustments you mentioned with my own wording
(attached and applied).  Let me know of any more needed adjustments.
Thanks.

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

  + It's impossible for everything to be true. +