Re: [PATCH] commit: Add commit_list prefix to reduce_heads function.

[Thiago Farina <tfransosi@gmail.com>]

On Sun, Dec 5, 2010 at 12:18 AM, Jonathan Nieder <jrnieder@gmail.com> wrote:
> Thiago Farina wrote:
>
>> Signed-off-by: Thiago Farina <tfransosi@gmail.com>
>
> 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)
>
What you want here? That I describe the functions in these files? Why
me? Why not the person who wrote them?

>  . next, describe their current meaning.  If this requires
>   apologizing for the name,
Apologize? For what? I don't understand what you mean here.

> 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.
>
I'd prefer to do just that step.

> That way, people used to the current functions would at least have
> some documentation to help them adjust.  What do you think?
>
I think it's a good procedure for someone more familiar with this
functions to do this. Perhaps, you or Junio?