strbuf.h: reorganize api function grouping headers

The original API doc had something like:

    Functions
    ---------

    * Life cycle

      ... some life-cycle functions ...

    * Related to the contents of the buffer

      ... functions related to contents ....

    etc

This grouping can be hard to read in the comment sources,
given the "*" in the comment lines, and the amount of text
between each section.

Instead, let's make a flat list of groupings, and underline
each as a section header. That makes them stand out, and
eliminates the weird half-phrase of "Related to...". Like:

    Functions related to the contents of the buffer
    -----------------------------------------------

Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Jeff King 2015-01-16 04:05:28 -05:00 committed by Junio C Hamano
parent 088c9a86ff
commit 14e2177a40

View File

@ -71,12 +71,8 @@ extern char strbuf_slopbuf[];
#define STRBUF_INIT { 0, 0, strbuf_slopbuf }
/**
* Functions
* ---------
*/
/**
* * Life Cycle
* Life Cycle Functions
* --------------------
*/
/**
@ -120,7 +116,8 @@ static inline void strbuf_swap(struct strbuf *a, struct strbuf *b)
/**
* * Related to the size of the buffer
* Functions related to the size of the buffer
* -------------------------------------------
*/
/**
@ -162,7 +159,8 @@ static inline void strbuf_setlen(struct strbuf *sb, size_t len)
/**
* * Related to the contents of the buffer
* Functions related to the contents of the buffer
* -----------------------------------------------
*/
/**
@ -201,7 +199,8 @@ extern int strbuf_cmp(const struct strbuf *, const struct strbuf *);
/**
* * Adding data to the buffer
* Adding data to the buffer
* -------------------------
*
* NOTE: All of the functions in this section will grow the buffer as
* necessary. If they fail for some reason other than memory shortage and the