[PATCH] refs: improve comments about "reading" argument of "resolve_ref"

[Christian Couder <chriscool@tuxfamily.org>]

From: Junio C Hamano <gitster@pobox.com>

Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
---
 refs.c |   30 ++++++++++++++++++++++++------
 1 files changed, 24 insertions(+), 6 deletions(-)

	Junio wrote:
	> So how about improving the comment that is misleading?

	Ok, let's do that. On top of your patch, I added a comment based
	on your previous email as a function header. Feel free to discard
	it or move it to "cache.h".

	Thanks,
	Christian. 

diff --git a/refs.c b/refs.c
index 39a3b23..d61893b 100644
--- a/refs.c
+++ b/refs.c
@@ -390,6 +390,21 @@ int resolve_gitlink_ref(const char *path, const char *refname, unsigned char *re
 	return retval;
 }
 
+/*
+ * resolve_ref: find what a ref points at
+ *
+ * If the "reading" argument is set, this function finds out what _object_
+ * the ref points at. This is called "reading" the ref, and the ref, if it
+ * is not symbolic, has to exist, and if it is symbolic, it has to point at
+ * an existing ref, because the "read" goes through the symref to the ref
+ * it points at.
+ *
+ * Otherwise, the access that is not "reading" does not have to be "writing";
+ * it can be merely checking _where it leads to_. If it is a prelude to
+ * "writing" to the ref, a write to a symref that points at yet-to-be-born
+ * ref will create the real ref pointed by the symref, so such a symref is
+ * not an error.
+ */
 const char *resolve_ref(const char *ref, unsigned char *sha1, int reading, int *flag)
 {
 	int depth = MAXDEPTH;
@@ -409,12 +424,15 @@ const char *resolve_ref(const char *ref, unsigned char *sha1, int reading, int *
 		if (--depth < 0)
 			return NULL;
 
-		/* Special case: non-existing file.
-		 * Not having the refs/heads/new-branch is OK
-		 * if we are writing into it, so is .git/HEAD
-		 * that points at refs/heads/master still to be
-		 * born.  It is NOT OK if we are resolving for
-		 * reading.
+		/*
+		 * Special case: non-existing file.
+		 * Not having the refs/heads/new-branch is not OK if
+		 * we are resolving for reading.  But not everybody
+		 * calls this function to learn what object the ref
+		 * points at.  E.g. it can be called to learn what the
+		 * symref points at.  Also if we are writing into it,
+		 * it is Ok for .git/HEAD to point at refs/heads/master
+		 * that does not exist yet.
 		 */
 		if (lstat(path, &st) < 0) {
 			struct ref_list *list = get_packed_refs();
-- 
1.6.0.1.338.g5e95.dirty