Re: [PATCH] document string_list_clear

[Jonathan Nieder <jrnieder@gmail.com>]

Stefan Beller wrote:
> On Tue, Dec 9, 2014 at 11:37 AM, Junio C Hamano <gitster@pobox.com> wrote:

>> Perhaps the API doc that currently says "Free" is the only thing
>> that needs fixing?  And perhaps add "See $doc" at the beginning of
>> the header and remove duplicated comments we already have in the
>> file?
>
> The reason I wrote this patch originally was because I seem to forget we have
> more than one place to document our APIs. If there are comments in the header
> I seem to have thought it were the only place where we have documentation.

How about this patch?

-- >8 --
Subject: put strbuf API documentation in one place

v1.8.1-rc0~61^2 (strbuf_split*(): document functions, 2012-11-04)
added some nice API documentation for a few functions to strbuf.h, to
complement the documentation at Documentation/technical/api-strbuf.
That was helpful because it meant one less hop for someone reading the
header to find API documentation.

In practice, unfortunately, it is too hard to remember that there
is documentation in two places.  The longer documentation comments
in the header made Documentation/technical/api-strbuf less
discoverable.  So move the information to
Documentation/technical/api-strbuf and drop the long comments.

Hopefully in the long term we will find a good way to
generate well organized Documentation/technical/api-* documents
from comments in headers and this problem will be eliminated
completely.

Short reminders in the header file are still okay.

Reported-by: Stefan Beller <sbeller@google.com>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/technical/api-strbuf.txt | 20 +++++++++++++++--
 strbuf.h                               | 40 ++--------------------------------
 2 files changed, 20 insertions(+), 40 deletions(-)

diff --git a/Documentation/technical/api-strbuf.txt b/Documentation/technical/api-strbuf.txt
index cca6543..a43facc 100644
--- a/Documentation/technical/api-strbuf.txt
+++ b/Documentation/technical/api-strbuf.txt
@@ -252,6 +252,11 @@ which can be used by the programmer of the callback as she sees fit.
 	destination. This is useful for literal data to be fed to either
 	strbuf_expand or to the *printf family of functions.
 
+`strbuf_addstr_xml_quoted`::
+
+	Append a string to a strbuf with the characters '<', '>', '&', and
+	'"' converted into XML entities.
+
 `strbuf_humanise_bytes`::
 
 	Append the given byte size as a human-readable string (i.e. 12.23 KiB,
@@ -266,6 +271,13 @@ which can be used by the programmer of the callback as she sees fit.
 	Add a formatted string prepended by a comment character and a
 	blank to the buffer.
 
+`xstrfmt`::
+`xstrvfmt`::
+
+	Create a newly allocated string using printf format.  You can do
+	this easily with a strbuf, but this provides a shortcut to save a
+	few lines.
+
 `strbuf_fread`::
 
 	Read a given size of data from a FILE* pointer to the buffer.
@@ -336,11 +348,15 @@ same behaviour as well.
 	terminator characters.  Some of these functions take a `max`
 	parameter, which, if positive, limits the output to that
 	number of substrings.
++
+For lighter-weight alternatives, see `string_list_split` and
+`string_list_split_in_place` from the
+link:api-string-list.html[string list API].
 
 `strbuf_list_free`::
 
-	Free a list of strbufs (for example, the return values of the
-	`strbuf_split()` functions).
+	Free a NULL-terminated list of strbufs (for example, the return
+	values of the `strbuf_split()` functions).
 
 `launch_editor`::
 
diff --git a/strbuf.h b/strbuf.h
index 652b6c4..f3c9bb6 100644
--- a/strbuf.h
+++ b/strbuf.h
@@ -58,56 +58,27 @@ static inline int strbuf_strip_suffix(struct strbuf *sb, const char *suffix)
 		return 0;
 }
 
-/*
- * Split str (of length slen) at the specified terminator character.
- * Return a null-terminated array of pointers to strbuf objects
- * holding the substrings.  The substrings include the terminator,
- * except for the last substring, which might be unterminated if the
- * original string did not end with a terminator.  If max is positive,
- * then split the string into at most max substrings (with the last
- * substring containing everything following the (max-1)th terminator
- * character).
- *
- * For lighter-weight alternatives, see string_list_split() and
- * string_list_split_in_place().
- */
-extern struct strbuf **strbuf_split_buf(const char *, size_t,
+extern struct strbuf **strbuf_split_buf(const char *str, size_t slen,
 					int terminator, int max);
 
-/*
- * Split a NUL-terminated string at the specified terminator
- * character.  See strbuf_split_buf() for more information.
- */
 static inline struct strbuf **strbuf_split_str(const char *str,
 					       int terminator, int max)
 {
 	return strbuf_split_buf(str, strlen(str), terminator, max);
 }
 
-/*
- * Split a strbuf at the specified terminator character.  See
- * strbuf_split_buf() for more information.
- */
 static inline struct strbuf **strbuf_split_max(const struct strbuf *sb,
 						int terminator, int max)
 {
 	return strbuf_split_buf(sb->buf, sb->len, terminator, max);
 }
 
-/*
- * Split a strbuf at the specified terminator character.  See
- * strbuf_split_buf() for more information.
- */
 static inline struct strbuf **strbuf_split(const struct strbuf *sb,
 					   int terminator)
 {
 	return strbuf_split_max(sb, terminator, 0);
 }
 
-/*
- * Free a NULL-terminated list of strbufs (for example, the return
- * values of the strbuf_split*() functions).
- */
 extern void strbuf_list_free(struct strbuf **);
 
 /*----- add data in your buffer -----*/
@@ -158,10 +129,7 @@ extern void strbuf_vaddf(struct strbuf *sb, const char *fmt, va_list ap);
 
 extern void strbuf_add_lines(struct strbuf *sb, const char *prefix, const char *buf, size_t size);
 
-/*
- * Append s to sb, with the characters '<', '>', '&' and '"' converted
- * into XML entities.
- */
+/* append s with <, >, &, and " converted to XML entities */
 extern void strbuf_addstr_xml_quoted(struct strbuf *sb, const char *s);
 
 static inline void strbuf_complete_line(struct strbuf *sb)
@@ -200,10 +168,6 @@ extern int fprintf_ln(FILE *fp, const char *fmt, ...);
 
 char *xstrdup_tolower(const char *);
 
-/*
- * Create a newly allocated string using printf format. You can do this easily
- * with a strbuf, but this provides a shortcut to save a few lines.
- */
 __attribute__((format (printf, 1, 0)))
 char *xstrvfmt(const char *fmt, va_list ap);
 __attribute__((format (printf, 1, 2)))
-- 
2.2.0.rc0.207.ga3a616c