[RFA] Fix documentation of snprintf and vsnprintf

[Dave Korn]

Eli Zaretskii wrote:
>> Date: Sat, 23 May 2009 15:29:20 +0100
>> From: Dave Korn <dave.korn.cygwin@googlemail.com>
>> CC: gcc@gcc.gnu.org, gcc-patches@gcc.gnu.org
>>
>>   I think it's still a little bit unclear:
>>
>>> +This function is similar to @code{sprintf}, but it will write at most
>>> +var{n} bytes (including the terminating null byte) to @var{buf}.
>>   It could still be perceived as ambiguous.  That sentence says that the
>> terminating null byte is included in the count of
>> "the-most-bytes-it-will-write", but it doesn't explicitly say that it won't be
>> truncated off like the rest of the characters if the output is too long.
> 
> I thought it did say that, as
> 
>   "write at most N bytes (including the terminating null byte)"
> 
> means that it will write no more than N bytes, and those N bytes
> include the null byte.

  Yes, the text can be taken to mean this as well, and that is clearly the
intended meaning once you know, but it's about how this sentence says the NUL
terminating byte should be *counted* the same as all the rest, it might seem
to imply that it is *treated* the same as all the rest - and it's not, it's
treated differently.

> However, I don't mind the text you suggest if people think it says the
> same more clearly:
> 
>> How about
>>
>>> +This function is similar to @code{sprintf}, but it will write at most
>>> +var{n} bytes (truncating the output if necessary, so that there is
>>> +always guaranteed to be a terminating null byte) to @var{buf}.
> 
> Or maybe we should make it clearer still:
> 
>  This function is similar to @code{sprintf}, but it will write to
>  @var{buf} at most @code{var{n}-1} bytes of text, followed by a
>  terminating null byte, for the total of @var{n} bytes.
> 
> WDYT?

  That WFM just fine too :)

    cheers,
      DaveK