Skip to content

Commit

Permalink
strbuf.h: drop boilerplate descriptions of strbuf_split_*
Browse files Browse the repository at this point in the history
The description of strbuf_split_buf says most of what
needs to be said for all of the split variants that take
strings, raw memory, etc. We have a boilerplate comment
above each that points to the first. This boilerplate
ends up making it harder to read, because it spaces out the
functions, which could otherwise be read as a group.

Let's drop the boilerplate completely, and mention the
variants in the top comment. This is perhaps slightly worse
for a hypothetical system which pulls the documentation for
each function out of the comment immediately preceding it.
But such a system does not yet exist, and anyway, the end
result of extracting the boilerplate comments would not lead
to a very easy-to-read result.  We would do better in the
long run to teach the extraction system about groups of
related functions.

Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
  • Loading branch information
Jeff King authored and Junio C Hamano committed Jan 16, 2015
1 parent 14e2177 commit f20e56e
Showing 1 changed file with 5 additions and 12 deletions.
17 changes: 5 additions & 12 deletions strbuf.h
Original file line number Diff line number Diff line change
Expand Up @@ -441,36 +441,29 @@ static inline int strbuf_strip_suffix(struct strbuf *sb, const char *suffix)
* substring containing everything following the (max-1)th terminator
* character).
*
* The most generic form is `strbuf_split_buf`, which takes an arbitrary
* pointer/len buffer. The `_str` variant takes a NUL-terminated string,
* the `_max` variant takes a strbuf, and just `strbuf_split` is a convenience
* wrapper to drop the `max` parameter.
*
* For lighter-weight alternatives, see string_list_split() and
* string_list_split_in_place().
*/
extern struct strbuf **strbuf_split_buf(const char *, size_t,
int terminator, int max);

/**
* Split a NUL-terminated string at the specified terminator
* character. See strbuf_split_buf() for more information.
*/
static inline struct strbuf **strbuf_split_str(const char *str,
int terminator, int max)
{
return strbuf_split_buf(str, strlen(str), terminator, max);
}

/**
* Split a strbuf at the specified terminator character. See
* strbuf_split_buf() for more information.
*/
static inline struct strbuf **strbuf_split_max(const struct strbuf *sb,
int terminator, int max)
{
return strbuf_split_buf(sb->buf, sb->len, terminator, max);
}

/**
* Split a strbuf at the specified terminator character. See
* strbuf_split_buf() for more information.
*/
static inline struct strbuf **strbuf_split(const struct strbuf *sb,
int terminator)
{
Expand Down

0 comments on commit f20e56e

Please sign in to comment.