From: Jonathan Nieder Date: Sun, 05 Dec 2010 02:18:38 GMT Subject: Re: [PATCH] commit: Add commit_list prefix to reduce_heads function. Message-ID: <20101205021837.GA24614@burratino> In-Reply-To: Thiago Farina wrote: > Signed-off-by: Thiago Farina I know that the context is part of an effort to make the commit_list functions into something more of a self-contained API, but the reader does not know that. Perhaps you could say some words about that in the change description: what's wrong with the current situation, what context does this change come from, and what positive effect would it have? Beyond that, I must say I do not think this goes far enough to seem useful. If I wondered what reduce_heads did, wouldn't commit_list_reduce_heads be even more confusing? (ignoring the typo) Perhaps a more natural way to proceed would be as follows: . first, collect the functions to be treated as a module and list them in Documentation/technical (in this case, perhaps api-revision-walking or a new api-commit-list) . next, describe their current meaning. If this requires apologizing for the name, that's a good hint that a name change might be worthwhile . finally, tweak signatures (names and arguments) based on the results from step 2 and update the documentation at the same time. That way, people used to the current functions would at least have some documentation to help them adjust. What do you think?