Re: [PATCH] document string_list_clear

[Junio C Hamano <gitster@pobox.com>]

Jonathan Nieder <jrnieder@gmail.com> writes:

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

If we later introduce string_list_free() that is in line with the
distinction between "free" and "clear" discussed on this thread, the
comment for this function needs to be fixed to "Clear the string
list.  See $doc". and that is not much different from "See $doc"
without the first sentence which is the function name.

Perhaps the API doc that currently says "Free" is the only thing
that needs fixing?  And perhaps add "See $doc" at the beginning of
the header and remove duplicated comments we already have in the
file?