Skip site navigation (1) Skip section navigation (2)

Re: libpq documentation cleanups (repost 3)

From: Bruce Momjian <bruce(at)momjian(dot)us>
To: Robert Haas <robertmhaas(at)gmail(dot)com>
Cc: PostgreSQL-development <pgsql-hackers(at)postgresql(dot)org>, Leslie S Satenstein <lsatenstein(at)yahoo(dot)com>
Subject: Re: libpq documentation cleanups (repost 3)
Date: 2011-01-13 17:09:09
Message-ID: 201101131709.p0DH99P14490@momjian.us (view raw or flat)
Thread:
Lists: pgsql-hackers
Robert Haas wrote:
> On Wed, Jan 12, 2011 at 8:54 PM, Bruce Momjian <bruce(at)momjian(dot)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(at)momjian(dot)us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

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

Attachment: /pgpatches/libpq_v2
Description: text/x-diff (2.2 KB)

In response to

pgsql-hackers by date

Next:From: David FetterDate: 2011-01-13 17:12:35
Subject: Re: kill -KILL: What happens?
Previous:From: Alex HunsakerDate: 2011-01-13 16:55:44
Subject: Re: arrays as pl/perl input arguments [PATCH]

Privacy Policy | About PostgreSQL
Copyright © 1996-2014 The PostgreSQL Global Development Group