Re: [PATCH] document string_list_clear

From: Jonathan Nieder <jrnieder@gmail.com>
Date: Dec 6, 2014, 02:04 UTC
Message-ID: <20141206020458.GR16345@google.com>
In-Reply-To: <1417830678-16115-1-git-send-email-sbeller@google.com>

Stefan Beller wrote:

Show 8 quoted lines

> 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.

[...]

Show 12 quoted lines

> --- 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