Re: [PATCH v3 1/2] Introduce strbuf_write_or_die()
- From
Eric Sunshine <sunshine@sunshineco.com>
- Date
- Mar 2, 2014, 20:05 UTC
- Message-ID
- <CAPig+cQfbxX0oH_tfaQt5PT0DP29hRZ8seZdJ-ssLDQbH=iJGQ@mail.gmail.com>
- In-Reply-To
- <1393745664-21077-1-git-send-email-faiz.off93@gmail.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().
Show 7 quoted lines
> --- > 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.
Show 7 quoted lines
> 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.
Show 19 quoted lines
> 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.
Show 17 quoted lines
> 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