From: Jeff King <peff@peff.net>
To: Jonathan Nieder <jrnieder@gmail.com>
Cc: Stefan Beller <sbeller@google.com>,
Junio C Hamano <gitster@pobox.com>,
"git@vger.kernel.org" <git@vger.kernel.org>,
Michael Haggerty <mhagger@alum.mit.edu>
Subject: [PATCH 4/4] strbuf.h: reorganize api function grouping headers
Date: Fri, 12 Dec 2014 16:32:36 -0500 [thread overview]
Message-ID: <20141212213235.GD27451@peff.net> (raw)
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
next prev parent reply other threads:[~2014-12-12 21:32 UTC|newest]
Thread overview: 49+ messages / expand[flat|nested] mbox.gz Atom feed top
2014-12-06 1:51 [PATCH] document string_list_clear Stefan Beller
2014-12-06 2:04 ` Jonathan Nieder
2014-12-06 5:27 ` Jeff King
2014-12-06 5:30 ` Jeff King
2014-12-09 19:41 ` Junio C Hamano
2014-12-09 20:15 ` Jeff King
2014-12-09 20:21 ` Jonathan Nieder
2014-12-09 19:37 ` Junio C Hamano
2014-12-09 19:48 ` Stefan Beller
2014-12-09 20:17 ` Jonathan Nieder
2014-12-09 20:27 ` Jeff King
2014-12-09 20:32 ` Stefan Beller
2014-12-09 20:46 ` Jeff King
2014-12-09 22:23 ` Jonathan Nieder
2014-12-09 23:18 ` Junio C Hamano
2014-12-10 8:52 ` Jeff King
2014-12-10 8:43 ` Jeff King
2014-12-10 9:18 ` Jonathan Nieder
2014-12-12 9:16 ` Jeff King
2014-12-12 18:31 ` Jonathan Nieder
2014-12-12 19:17 ` Junio C Hamano
2014-12-12 19:19 ` Stefan Beller
2014-12-12 19:29 ` Jeff King
2014-12-12 19:24 ` Jeff King
2014-12-12 19:35 ` Jonathan Nieder
2014-12-12 21:27 ` Jeff King
2014-12-12 21:28 ` [PATCH 1/4] strbuf: migrate api-strbuf.txt documentation to strbuf.h Jeff King
2014-12-12 21:40 ` Jeff King
2014-12-12 22:16 ` Junio C Hamano
2014-12-12 22:30 ` Jonathan Nieder
2014-12-12 21:28 ` [PATCH 2/4] strbuf.h: drop asciidoc list formatting from API docs Jeff King
2014-12-12 22:19 ` Junio C Hamano
2014-12-12 22:37 ` Jonathan Nieder
2014-12-12 21:30 ` [PATCH 3/4] strbuf.h: format asciidoc code blocks as 4-space indent Jeff King
2014-12-12 22:39 ` Jonathan Nieder
2014-12-14 17:42 ` Michael Haggerty
2014-12-12 21:32 ` Jeff King [this message]
2014-12-12 22:46 ` [PATCH 4/4] strbuf.h: reorganize api function grouping headers Jonathan Nieder
2014-12-12 22:32 ` [PATCH] document string_list_clear Stefan Beller
2014-12-10 20:09 ` Michael Haggerty
2014-12-10 21:51 ` Jonathan Nieder
2014-12-10 22:28 ` Junio C Hamano
2014-12-10 22:37 ` Jonathan Nieder
2014-12-10 23:04 ` Junio C Hamano
2014-12-10 23:08 ` Jonathan Nieder
2014-12-09 22:49 ` Jonathan Nieder
2014-12-09 23:07 ` Stefan Beller
2014-12-09 23:15 ` Jonathan Nieder
2014-12-09 20:00 ` Jonathan Nieder
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20141212213235.GD27451@peff.net \
--to=peff@peff.net \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=jrnieder@gmail.com \
--cc=mhagger@alum.mit.edu \
--cc=sbeller@google.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).