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@xxxxxxxx>
---
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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html