@matheusbsbs / matheus-bagliano / commits / f20e56e202

strbuf.h: drop boilerplate descriptions of strbuf_split_*

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>

Jeff King committed Jan 16, 2015 at 04:05 UTC f20e56e202fa2a6cd3faa1710ed9f600ba58ce1d

1 file changed +5 -12

strbuf.h

+5 -12

@@ -441,36 +441,29 @@ static inline int strbuf_strip_suffix(struct strbuf *sb, const char *suffix)

441 * substring containing everything following the (max-1)th terminator

442 * character).

443 *

444 + * The most generic form is `strbuf_split_buf`, which takes an arbitrary

445 + * pointer/len buffer. The `_str` variant takes a NUL-terminated string,

446 + * the `_max` variant takes a strbuf, and just `strbuf_split` is a convenience

447 + * wrapper to drop the `max` parameter.

448 + *

449 * For lighter-weight alternatives, see string_list_split() and

450 * string_list_split_in_place().

451 */

452 extern struct strbuf **strbuf_split_buf(const char *, size_t,

453 int terminator, int max);

454

450 -/**

451 - * Split a NUL-terminated string at the specified terminator

452 - * character. See strbuf_split_buf() for more information.

453 - */

455 static inline struct strbuf **strbuf_split_str(const char *str,

456 int terminator, int max)

457 {

458 return strbuf_split_buf(str, strlen(str), terminator, max);

459 }

460

460 -/**

461 - * Split a strbuf at the specified terminator character. See

462 - * strbuf_split_buf() for more information.

463 - */

461 static inline struct strbuf **strbuf_split_max(const struct strbuf *sb,

462 int terminator, int max)

463 {

464 return strbuf_split_buf(sb->buf, sb->len, terminator, max);

465 }

466

470 -/**

471 - * Split a strbuf at the specified terminator character. See

472 - * strbuf_split_buf() for more information.

473 - */

467 static inline struct strbuf **strbuf_split(const struct strbuf *sb,

468 int terminator)

469 {