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

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 13, 2011, 18:48 UTC
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 <mhagger@alum.mit.edu>
>
>
> Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>

Show 6 quoted lines

> -/** 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);