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

[Jeremiah Mahler <jmmahler@gmail.com>]

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 <jmmahler@gmail.com> wrote:
> > 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.
> 
> > Signed-off-by: Jeremiah Mahler <jmmahler@gmail.com>
> > ---
> >  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.
> 
> > +`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