Re: [PATCH] document string_list_clear

From: Junio C Hamano <gitster@pobox.com>
Date: Dec 9, 2014, 19:37 UTC
Message-ID: <xmqq7fy0mx70.fsf@gitster.dls.corp.google.com>
In-Reply-To: <20141206020458.GR16345@google.com>

Jonathan Nieder <jrnieder@gmail.com> writes:

Show 17 quoted lines

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