Re: [PATCH 01/14] cache.h: add comments for git_path() and git_path_submodule()

mhagger@alum.mit.edu writes:

+
+/*
+ * Return the path of a file within get_git_dir().  The arguments
+ * should be printf-like arguments that produce the filename relative
+ * to get_git_dir().  Return the resulting path, or "/bad-path/" if
+ * there is an error.
+ */
 extern char *git_path(const char *fmt, ...) __attribute__((format (printf, 1, 2)));

Ok.

+/*
+ * Return the path of a file within the submodule located at path.

This is confusing. Does this "file within the submodule" refer to files
like "Makefile" tracked in a submodule at "dir"?  Your description for
git_path() above makes it clear that the function is about files like
"index" and "HEAD" that are part of the control information for the
current project, but the above gives an impression that you are talking
about files in the working tree of the submodule.

+ * The other arguments should be printf-like arguments that produce
+ * the filename relative to "<path>/.git".  If "<path>/.git" is a

And the reader is puzzled by the sudden mention of <path>/.git here.

+ * gitlink file, follow it to find the actual submodule git path.
+ * Return the resulting path, or "/bad-path/" if there is an error.
+ */
 extern char *git_path_submodule(const char *path, const char *fmt, ...)
 	__attribute__((format (printf, 2, 3)));