From: Jeff King <peff@peff.net>
Date: Fri, 16 Jan 2015 09:05:28 +0000 (-0500)
Subject: strbuf.h: reorganize api function grouping headers
X-Git-Tag: v2.4.0-rc0~91^2~2
X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/14e2177a40ca5861f0518cb6bbe0a6856ffa7552

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

diff --git a/strbuf.h b/strbuf.h
index caa4dad663..6fa7156351 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
+ * -----------------------------------------------
  */
 
 /**
@@ -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