Re: [PATCH/RFC v1 2/5] add strbuf_set operations documentation

Eric,

On Mon, Jun 09, 2014 at 05:53:49AM -0400, Eric Sunshine wrote:

On Mon, Jun 9, 2014 at 4:36 AM, Jeremiah Mahler [off-list ref] wrote:

quoted

Add documentation of the strbuf_set operations to
technical/api-strbuf.txt.

Since this patch is concise and so closely related to patch 1/5, it
probably should be squashed into that one.

Fixed.

More below.

quoted

Signed-off-by: Jeremiah Mahler <redacted>
---
 Documentation/technical/api-strbuf.txt | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/Documentation/technical/api-strbuf.txt b/Documentation/technical/api-strbuf.txt
index 077a709..ab430d9 100644
--- a/Documentation/technical/api-strbuf.txt
+++ b/Documentation/technical/api-strbuf.txt

@@ -149,6 +149,24 @@ Functions
        than zero if the first buffer is found, respectively, to be less than,
        to match, or be greater than the second buffer.

+* Setting the buffer
+
+`strbuf_set`::
+
+    Set the buffer to some data up to a given length.

I personally find this slightly ambiguous. Upon reading it, the first
question that pops into my mind is whether or not the existing strbuf
content is replaced (even though "set" should imply that it is). I
wonder if it would make sense to rewrite as:

    Set the buffer to [...], replacing the old content
    of the buffer.

Alternately:

    Replace the buffer content with [...].

On a second reading, I agree that it is ambigous.  'Replace' is much
more clear.  Great suggestion.

Ditto for the others.

quoted

+`strbuf_setstr`::
+
+       Set the buffer to a NUL-terminated string.
+
+`strbuf_setf`::
+
+       Set the buffer to a formatted string.
+
+`strbuf_setbuf`::
+
+       Set the current buffer to the contents of some other buffer.
+
 * Adding data to the buffer

 NOTE: All of the functions in this section will grow the buffer as necessary.
--

-- 
Jeremiah Mahler
jmmahler@gmail.com
http://github.com/jmahler