From: Junio C Hamano Date: Thu, 13 Oct 2011 18:48:35 GMT Subject: Re: [PATCH 06/14] resolve_gitlink_ref(): improve docstring Message-ID: <7vehyg4tj0.fsf@alter.siamese.dyndns.org> In-Reply-To: <1318492715-5931-7-git-send-email-mhagger@alum.mit.edu> mhagger@alum.mit.edu writes: > From: Michael Haggerty > > > Signed-off-by: Michael Haggerty > -/** 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);