Heiko Voigt <hvoigt@xxxxxxxxxx> writes: > Signed-off-by: Heiko Voigt <hvoigt@xxxxxxxxxx> > --- > Documentation/technical/api-ref-iteration.txt | 73 +++++++++++++++++++++++++ > 1 files changed, 73 insertions(+), 0 deletions(-) > create mode 100644 Documentation/technical/api-ref-iteration.txt > +Submodules > +---------- > + > +If you want to iterate the refs of a submodule you first need to call > + > + add_submodule_odb(submodule) > + > +and test whether that succeeds. Hmm, this should probably be explained a bit deeper or not at all. For example, what is "submodule" here? A path to the submodule directory? The name of submodule? What is the unwanted consequence of adding this extra object database into your process (e.g. you can no longer tell if an object exists in the superproject, as it may now come from the submodule's object database)? Can you get rid of it? How does this function signal failures? What is the symptom if you forget this call and used the iteration in the submodule (e.g. "we do not see any ref"; "we see only some ref but not all"; "the call crashes the process")? > + > +(Heiko Voigt) Please drop this line for two reasons. Initially I added these parenthesized names at the end for placeholder pages to name people who are responsible for the _code_ the document describes, so that the ones who help documentation would know who to nag to get the necessary information. With your description, people who are interested in documenting this API more would know that for_each_ref() and friends are the topic and can find out whom to harrass. Besides, with only two commits to refs.c, I doubt you would want to be the primary source of information for other people to bug in order to enhance the API description in this file. Thanks. -- 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