Re: [PATCH v3 1/2] Introduce strbuf_write_or_die()

[Eric Sunshine <sunshine@sunshineco.com>]

On Sun, Mar 2, 2014 at 2:34 AM, Faiz Kothari <faiz.off93@gmail.com> wrote:
> Signed-off-by: Faiz Kothari <faiz.off93@gmail.com>

Place your sign off below the commit message.

> Introduced a new function strbuf.c:strbuf_write_or_die()
> to the strbuf family of functions. Now use this API instead
> of write_or_die.c:write_or_die()

You want to explain what this patch is doing in imperative tone. Use
"Introduce" rather than "Introduced". The first sentence correctly
states what the patch is doing, however, the second sentence explains
what the next patch is doing, so it doesn't belong here. So, your
commit message for this patch might become:

    Subject: strbuf: introduce strbuf_write_or_die()

    Add strbuf convenience wrapper around lower-level write_or_die().

> ---
> Hi,
> Thanks for the suggestions and feedbacks.
> As Johannes Sixt  pointed out, the function is now defined
> in strbuf.c and prototype added to strbuf.h
> Also, replaced if(!sbuf) with assert(sbuf) and split the patch into two
> as pointed out by Eric Sunshine.

Good explanation of what changed since the last attempt.

> As far as justification is concerned, I am not able to come up with
> a satisfactory justification. Apart from, that it makes life of the
> programmer a little easier and if we add a few more functions
> to thestrbuf API, we can make strbuf completely opaque. I am open
> to views and since I haven't used this API extensively, I cannot
> comment for what is missing and what is required. But I am going through it.
> Also, once this patch is OK, I'll add documentation for the API.

It's a good idea to add documentation when you add the function
itself, otherwise reviewers will have to wait yet another round to
review that addition. In this case, the documentation will likely be
one line, so it shouldn't be a particular burden to write it.

> Thanks again for the feedback.
>
>  strbuf.c |    6 ++++++
>  strbuf.h |    1 +
>  2 files changed, 7 insertions(+)
>
> diff --git a/strbuf.c b/strbuf.c
> index 83caf4a..337a70c 100644
> --- a/strbuf.c
> +++ b/strbuf.c
> @@ -477,6 +477,12 @@ int strbuf_read_file(struct strbuf *sb, const char *path, size_t hint)
>         return len;
>  }
>
> +void strbuf_write_or_die(const struct strbuf *sb, int fd)
> +{
> +       assert(sb);
> +       write_or_die(fd, sb->buf, sb->len);
> +}

Nice. Much better than previous versions of the patch.

>  void strbuf_add_lines(struct strbuf *out, const char *prefix,
>                       const char *buf, size_t size)
>  {
> diff --git a/strbuf.h b/strbuf.h
> index 73e80ce..6aadb6d 100644
> --- a/strbuf.h
> +++ b/strbuf.h
> @@ -156,6 +156,7 @@ extern size_t strbuf_fread(struct strbuf *, size_t, FILE *);
>  /* XXX: if read fails, any partial read is undone */
>  extern ssize_t strbuf_read(struct strbuf *, int fd, size_t hint);
>  extern int strbuf_read_file(struct strbuf *sb, const char *path, size_t hint);
> +extern void strbuf_write_or_die(const struct strbuf *sb, int fd);
>  extern int strbuf_readlink(struct strbuf *sb, const char *path, size_t hint);
>
>  extern int strbuf_getwholeline(struct strbuf *, FILE *, int);
> --
> 1.7.9.5