Re: [PATCH 2/2] Document the string_list structure

From: Jeff King <peff@peff.net>
Date: Sep 21, 2017, 16:24 UTC
Message-ID: <20170921162414.h3lapq6ahdbamlu6@sigill.intra.peff.net>
In-Reply-To: <20170921124338.26626-3-hanwen@google.com>

On Thu, Sep 21, 2017 at 02:43:38PM +0200, Han-Wen Nienhuys wrote:

Show 22 quoted lines

> Signed-off-by: Han-Wen Nienhuys <hanwen@google.com>
> ---
>  string-list.h | 6 ++++++
>  1 file changed, 6 insertions(+)
> 
> diff --git a/string-list.h b/string-list.h
> index 29bfb7ae4..08b534166 100644
> --- a/string-list.h
> +++ b/string-list.h
> @@ -8,6 +8,12 @@ struct string_list_item {
>  
>  typedef int (*compare_strings_fn)(const char *, const char *);
>  
> +/* A resizable array of strings. The strings are owned if
> + * 'strdup_strings' is set. It can be used as a sorted array, and a
> + * custom comparison may be given in 'cmp'. The field 'items[i].util'
> + * may be used to implement an array of pairs. In that case, the
> + * caller is responsible for managing memory pointed to by 'util'.
> + */
>  struct string_list {
>  	struct string_list_item *items;
>  	unsigned int nr, alloc;

There's a considerable amount of documentation for string-list in Documentation/technical/api-string-list.txt.

Perhaps we should look at migrating it into string-list.h, where it's more likely to be found (and kept up to date). We did something similar for strbuf.h a while back, and I think the result is much better. See the commits in:

  git log bdfdaa4978^..d468fa2721

for an example.

-Peff