[demo/patch 0/3] Re: [PATCH] Documentation: document the string-list macros.

[Jonathan Nieder <jrnieder@gmail.com>]

Thiago Farina wrote:

> --- a/Documentation/technical/api-string-list.txt
> +++ b/Documentation/technical/api-string-list.txt
> @@ -52,6 +52,18 @@ However, if you use the list to check if a certain string was added
>  already, you should not do that (using unsorted_string_list_has_string()),
>  because the complexity would be quadratic again (but with a worse factor).
>  
> +Macros
> +------
> +
> +`STRING_LIST_INIT_NODUP`::
> +
> +	Initialize the members and set the `strdup_strings` member to 0.
> +
> +`STRING_LIST_INIT_DUP`::
> +
> +	Initialize the members and set the `strdup_strings` member to 1.

After reading that, one might be tempted to write

	struct string_list x;
	STRING_LIST_INIT_NODUP(x);

, no?  In other words, I don't find the text very clear.

If you like working by example (like I do) then api-strbuf.txt might
give a good indication of how this sort of thing can be helpfully
documented.

Maybe something in this direction?

Patch #3 in particular is very rough and ought to be split up for
easier review.  This is not meant for application, just to give an
idea.

Jonathan Nieder (3):
  string-list: introduce string_list_init()
  string-list: document ...
  Make initialization of string_lists more consistent

 Documentation/technical/api-string-list.txt |   18 +++++++++------
 builtin/apply.c                             |    8 +++---
 builtin/blame.c                             |    4 +-
 builtin/clean.c                             |    2 +-
 builtin/commit.c                            |    4 +-
 builtin/fetch.c                             |   13 ++++-------
 builtin/fmt-merge-msg.c                     |   13 ++++++-----
 builtin/log.c                               |    9 ++-----
 builtin/mailsplit.c                         |    1 +
 builtin/notes.c                             |    4 +-
 builtin/remote.c                            |   30 +++++++++++++-------------
 builtin/shortlog.c                          |   25 ++++++++++++---------
 diff-no-index.c                             |    1 +
 mailmap.c                                   |   17 +++++++++-----
 mailmap.h                                   |    2 +-
 merge-recursive.c                           |   16 ++++++++------
 notes.c                                     |    4 +-
 pretty.c                                    |    5 ++-
 reflog-walk.c                               |    1 +
 resolve-undo.c                              |    8 +++---
 revision.c                                  |    7 ++++-
 string-list.c                               |   28 +++++++++++++++++++++---
 string-list.h                               |    4 +++
 submodule.c                                 |    4 +-
 wt-status.c                                 |    6 ++--
 25 files changed, 137 insertions(+), 97 deletions(-)

-- 
1.7.2.3