Try to use clearer language in buffer docs

[sarna]

I wasn't sure if buffers would grow automatically on all buffer/push* functions, and what the "buffer overflow" meant. This is my attempt at clarifying that, but I don't love it, so I welcome any suggestions :)

[sogaiu]

Some ideas follow...

---

If you want a slight bit of compression, I've taken to using "needed" instead of "necessary" in a variety of contexts.

That could manifest as:

• "Expands buffer as needed."
• "Expands buffer if needed."

Above backticks have been used and the definite article has been eliminated.

FWIW, both words are currently used according to the Core API page.

---

Here are some more candidate phrases for a different portion:

• "Throws an error if size limit is exceeded."
• "Throws an error beyond size limit."

[sarna]

Thanks, @sogaiu!

As for the first suggestion - I'm not against it, but I tried to fit into the existing style. IMO if we change the style in this sentence, we should change it in all buffer docstrings. Not sure if that'd fit into this PR, as the scope is a bit different?

As for the second one - I understand that "reached" is incorrect? From a quick test ((for i 0 math/int32-max (buffer/push buf 0))) it looks like it. I thought "will" was more fitting there, but I'm not a native speaker, so probably not :) I'll adjust the wording.

[sogaiu]

For the first point, I doubt it would be rejected to expand the scope, but please feel free to do as you see fit [1]. I think we would be benefitting from what you've suggested already :)

---

Regarding "reached", it felt vague to me about whether that includes "goes beyond" [2] -- which seems like it would be the more common case. It's easy to say "exceeds" or "surpasses" instead and I didn't think of significant downsides (there might be though).

Those alternatives seem closer to the code that does the checking:

(int64_t)n + buffer->count > INT32_MAX

but may be that's not that important.

I think this could be a case of it being rather difficult to briefly explain certain sorts of things precisely in human language (though may be others could do better!).

As I understand it, technically what's happening is that a request is made to add to a buffer which already has some size. Then the total number of items that would result if adding were to be successful is computed. If that computed total exceeds the limit, an error is thrown.

So the computed total exceeds the limit but the actual number of items in the buffer does not (which was what the original docstring (what's currently on the master branch) seemed to suggest).

I think:

Throws an error if size limit were to be exceeded if an attempt is made to add too many items.

might be more accurate, but doesn't really gain us much for all of the extra prose.

So what I see in your latest changes in a68edd1:

Throws an error if size limit is exceeded.

seems "good enough" (TM) to me (and an improvement over the text that's currently at the tip of the master branch).

---

[1] Though I don't decide what gets in 😅

[2] Imagine code that tried to add one thing at a time and as soon as a limit was arrived at, it would stop. That's not what happens here ofc.