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

From: Brandon Williams <[email-masked]>
Date: Thu, 21 Sep 2017 10:52:57 -0700

On 09/21, Han-Wen Nienhuys wrote:
> Signed-off-by: Han-Wen Nienhuys <[email-masked]>
> ---
>  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

nit: the start of the comment block should be on its own line:

  /*
   * A resizable ...

> + * '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'.
> + */

The util field can be freed if 'free_util' is set when calling
string_list_clear() but yeah, in general the caller is managing that
memory especially if a complex free function is required (in the case of
allocating a struct with dynamically allocated fields to be stored in
the util feild).

Just pointing that out, and I'm happy with this and the previous patch.

>  struct string_list {
>  	struct string_list_item *items;
>  	unsigned int nr, alloc;
> -- 
> 2.14.1.821.g8fa685d3b7-goog
> 

-- 
Brandon Williams