Jonathan Nieder <jrnieder@xxxxxxxxx> 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? -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html