Re: [PATCH 06/14] resolve_gitlink_ref(): improve docstring

mhagger@alum.mit.edu writes:

From: Michael Haggerty <redacted>


Signed-off-by: Michael Haggerty <redacted>

-/** resolve ref in nested "gitlink" repository */
+/**
+ * Resolve refname in the nested "gitlink" repository that is located
+ * at name.  If the resolution is successful, return 0 and set sha1 to
+ * the name of the object; otherwise, return a non-zero value.
+ */

It is clear that "refname" would refer to things like "refs/heads/master",
but "name" is still not clear enough with the description. 'repository
that is located at name' hints that we may be dealing with more than one
repository and 'name' is a way to identify which one, but perhaps "path"
or "submodule" a much clearer way to indicate what the code is doing.

At the UI level, a submodule has "name" and "path" that are often the same
but can be different (e.g. when the superproject moves a submodule that
used to be bound to path "dir" to a different location, only the latter
should change). I do not think resolve_gitlink_ref() takes the submodule
name, but it takes the path to the submodule in the superproject. In that
sense, "submodule_path" would be the clearest descriptive name for this
parameter.

 extern int resolve_gitlink_ref(const char *name, const char *refname, unsigned char *sha1);