Clarify return values of vsnprintf-s-vsnprintf-s-vsnprintf-s-l-vsnwprintf-s-vsnwprintf-s-l

[definedrisk]

No description provided.

[PRMerger18]

@definedrisk : Thanks for your contribution! The author(s) have been notified to review your proposed change.

[TylerMSFT]

@definedrisk - thanks for the contribution. I've been away at a conference. I'll take a look at this and get back to you.

[TylerMSFT]

Thank you for trying to clear this up. I wonder if we can do a little more to clear this up. What do you think of updating your change like this:

• If count is less than the number of characters of data, or is _TRUNCATE, as much of the string as will fit in buffer is written and the functions returns -1 without invoking the invalid parameter handler.
• If the storage required to store count characters of data and a terminating NULL exceeds sizeOfBuffer, the invalid parameter handler is invoked as described in Parameter Validation. If execution continues after the invalid parameter handler, these functions set buffer to an empty string, set errno to ERANGE, and return -1.

[PRMerger8]

@definedrisk : Thanks for your contribution! The author(s) have been notified to review your proposed change.

[PRMerger6]

@definedrisk : Thanks for your contribution! The author(s) have been notified to review your proposed change.

[definedrisk]

I think I wanted to highlight that there is a subtle difference between truncation with a full buffer and truncation caused by sending more than count characters of data...

• If the storage required to store the data with a terminating null exceeds sizeOfBuffer, the invalid parameter handler is invoked, as described in Parameter Validation. If execution continues after the invalid parameter handler, these functions set buffer to an empty string, set errno to ERANGE, and return -1.

• If count is _TRUNCATE and the data with a terminating null exceeds sizeOfBuffer, then as much of the string as will fit in buffer is written. If count is less than sizeOfBuffer but the data exceeds count characters, then the first count characters are written. Either way some truncation of the data occurs and -1 is returned without invoking the invalid parameter handler.

[TylerMSFT]

Thank you for the updates.
I believe the first statement is now incorrect. The invalid parameter isn't invoked if count == _TRUNCATE. We need the 'unless' part in there. Then the clarifying points that follow can flesh out the details. It'd also be good to put each condition on it's own line. When it's all together (as it unfortunately was in the original), it's hard to tease out the flow quickly. We should start most general and get more specific in with each following point about the behavior. Thanks for hanging in there with me on this.

[PRMerger8]

@definedrisk : Thanks for your contribution! The author(s) have been notified to review your proposed change.

[ghost]

All CLA requirements met.

[PRMerger8]

@definedrisk : Thanks for your contribution! The author(s) have been notified to review your proposed change.

[definedrisk]

I moved the second sentence of the first paragraph of Return Value section to the Remarks section as it is not directly related to return value, I thought it was better placed as a remark. If you disagree I will move back.

[TylerMSFT]

I think it was good to move the part of compliance and backward compatibility to the remarks section.
Thank you for making the docs better! People will benefit from the more complete explanation about what this function returns that you've worked out here.

[TylerMSFT]

Thank you, @definedrisk Really appreciate working with you on this.
#sign-off