Re: [PATCH] document string_list_clear

[Jonathan Nieder <jrnieder@gmail.com>]

Stefan Beller wrote:

> Signed-off-by: Stefan Beller <sbeller@google.com>
> ---
>
>  Just stumbled accross this one and wasn't sure if it also frees up
>  the memory involved.
>
>  string-list.h | 5 +++++
>  1 file changed, 5 insertions(+)

Sounds reasonable.  Documentation/technical/api-string-list.txt
documents these functions more fully.  The right balance between
documenting things in two places vs. adding "see also" pointers vs.
just putting the highlights in one of the two places isn't obvious to
me.

[...]
> --- a/string-list.h
> +++ b/string-list.h
> @@ -21,6 +21,11 @@ struct string_list {
>  void string_list_init(struct string_list *list, int strdup_strings);
>  
>  void print_string_list(const struct string_list *p, const char *text);
> +
> +/*
> + * Clears the string list, so it has zero items. All former items are freed.
> + * If free_util is true, all util pointers are also freed.
> + */
>  void string_list_clear(struct string_list *list, int free_util);

The api doc says

	Free a string_list. The `string` pointer of the items will be freed in
	case the `strdup_strings` member of the string_list is set. The second
	parameter controls if the `util` pointer of the items should be freed
	or not.

One option here would be to say

	Free a string_list.  See Documentation/technical/api-string-list.txt
	for details.

That reminds me: why do we call this string_list_clear instead of
string_list_free?

Thanks,
Jonathan