On Thu, Sep 4, 2014 at 1:00 PM, Robert Haas [via PostgreSQL] < ml-node+s1045698n581780...@n5.nabble.com> wrote:
> On Thu, Sep 4, 2014 at 12:53 PM, Bruce Momjian <[hidden email] > <http://user/SendEmail.jtp?type=node&node=5817809&i=0>> wrote: > > > On Thu, Sep 4, 2014 at 12:52:14PM -0400, Robert Haas wrote: > >> On Wed, Sep 3, 2014 at 6:24 PM, Bruce Momjian <[hidden email] > <http://user/SendEmail.jtp?type=node&node=5817809&i=1>> wrote: > >> > On Fri, May 9, 2014 at 12:03:36PM -0400, Robert Haas wrote: > >> >> On Thu, May 8, 2014 at 5:21 PM, Tom Lane <[hidden email] > <http://user/SendEmail.jtp?type=node&node=5817809&i=2>> wrote: > >> >> > Perhaps the text should be like this: > >> >> > > >> >> > The result is 1 if the termination message was sent; or in > nonblocking > >> >> > mode, this may only indicate that the termination message was > successfully > >> >> > queued. (In nonblocking mode, to be certain that the data has > been sent, > >> >> > you should next wait for write-ready and call > <function>PQflush</>, > >> >> > repeating until it returns zero.) Zero indicates that the > function could > >> >> > not queue the termination message because of full buffers; this > will only > >> >> > happen in nonblocking mode. (In this case, wait for write-ready > and try > >> >> > the PQputCopyEnd call again.) If a hard error occurs, -1 is > returned; you > >> >> > can use <function>PQerrorMessage</function> to retrieve details. > >> >> > >> >> That looks pretty good. However, I'm realizing this isn't the only > >> >> place where we probably need to clarify the language. Just to take > >> >> one example near at hand, PQputCopyData may also return 1 when it's > >> >> only queued the data; it seems to try even less hard than > PQputCopyEnd > >> >> to ensure that the data is actually sent. > >> > > >> > Uh, where are we on this? > >> > >> I think someone needs to take Tom's proposed language and make it into > >> a patch. And figure out which other functions in the documentation > >> need similar updates. > > > > OK, did David G Johnston email comments from today help here? > > I didn't look at them in detail, but they don't seem to match the > style of our documentation generally. > > Specific observations would help though that is partly the idea - I've been more focused on clarity and organization even if it requires deviating from the current general documentation style. If this is not acceptable I'm happy to incorporate the ideas of others to try and get the best of both worlds. David J. -- View this message in context: http://postgresql.1045698.n5.nabble.com/PQputCopyEnd-doesn-t-adhere-to-its-API-contract-tp5803240p5817812.html Sent from the PostgreSQL - hackers mailing list archive at Nabble.com.
