On Sun, Dec 5, 2010 at 12:18 AM, Jonathan Nieder <jrnieder@xxxxxxxxx> wrote: > Thiago Farina wrote: > >> Signed-off-by: Thiago Farina <tfransosi@xxxxxxxxx> > > 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? -- 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