[PATCH 4/4] strbuf.h: reorganize api function grouping headers

From: Jeff King <peff@peff.net>
Date: Dec 12, 2014, 21:32 UTC
Message-ID: <20141212213235.GD27451@peff.net>
In-Reply-To: <20141212212726.GA26284@peff.net>

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 standout, 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>
---

If you look at the original header file, these groupings actually did exist (though we did not remotely follow them as functions were added), and looked like:

  /* ---- content related ---- */

I'd be happy with something like that, too, but went with the style that matched the "Data Structures" header.

 strbuf.h | 14 ++++++--------
 1 file changed, 6 insertions(+), 8 deletions(-)

diff --git a/strbuf.h b/strbuf.h
index 078b805..8649a0a 100644
--- a/strbuf.h
+++ b/strbuf.h
@@ -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
+ * -----------------------------------------------
  */
 
 /**

-- 
2.2.0.454.g7eca6b7