On Mon Mar 25, 2024 at 1:44 PM CDT, Robert Haas wrote:
> On Fri, Mar 22, 2024 at 4:58 PM Tristan Partin <tristan@neon.tech> wrote:
> > I had a question about parameter naming. Right now I have a mix of
> > camel-case and snake-case in the function signature since that is what
> > I inherited. Should I change that to be consistent? If so, which case
> > would you like?
>
> Uh... PostgreSQL is kind of the wild west in that regard. The thing to
> do is look for nearby precedents, but that doesn't help much here
> because in the very same file, libpq-fe.h, we have:
>
> extern int PQsetResultAttrs(PGresult *res, int numAttributes,
> PGresAttDesc *attDescs);
> extern int PQsetvalue(PGresult *res, int tup_num, int field_num,
> char *value, int len);
>
> Since the existing naming is consistent with one of those two styles,
> I'd probably just leave it be.
>
> + The function returns a value greater than <literal>0</literal>
> if the specified condition
> + is met, <literal>0</literal> if a timeout occurred, or
> <literal>-1</literal> if an error
> + or interrupt occurred. In the event <literal>forRead</literal> and
>
> We either need to tell people how to find out which error it was, or
> if that's not possible and we can't reasonably make it possible, we
> need to tell them why they shouldn't care. Because there's nothing
> more delightful than someone who shows up and says "hey, I tried to do
> XYZ, and I got an error," as if that were sufficient information for
> me to do something useful.
>
> + <literal>end_time</literal> is the time in the future in
> seconds starting from the UNIX
> + epoch in which you would like the function to return if the
> condition is not met.
>
> This sentence seems a bit contorted to me, like maybe Yoda wrote it. I
> was about to try to rephrase it and maybe split it in two when I
> wondered why we need to document how time_t works at all. Can't we
> just say something like "If end_time is not -1, it specifies the time
> at which this function should stop waiting for the condition to be
> met" -- and maybe move it to the end of the first paragraph, so it's
> before where we list the meanings of the return values?
Incorporated feedback, I have :).
--
Tristan Partin
Neon (https://neon.tech)