Re: [PATCH] document string_list_clear

From

Jonathan Nieder <jrnieder@gmail.com>

Date

Dec 9, 2014, 20:17 UTC

Message-ID

<20141209201713.GY16345@google.com>

In-Reply-To

<CAGZ79kbk4SXEXKzn-V8c4zCQU8m8ub+VkKhmub-bFoLZT1WWpA@mail.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

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