Improve documentation comments.

3 files changed, 15 insertions, 1 deletions

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index ba042245fd6..029db96d3ab 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,7 @@
+2010-04-09  Eric Raymond  <esr@snark.thyrsus.com>
+
+        * vc-hooks.el, vc-git.el: Improve documentation comments.
+
 2010-04-08  Stefan Monnier  <monnier@iro.umontreal.ca>
 
         Fix some of the problems in defsubst* (bug#5728).
diff --git a/lisp/vc-git.el b/lisp/vc-git.el
index 9283e5dcfcf..c1ca48a5b78 100644
--- a/lisp/vc-git.el
+++ b/lisp/vc-git.el
@@ -171,7 +171,14 @@ If nil, use the value of `vc-diff-switches'.  If t, use no switches."
 
 (defun vc-git-state (file)
   "Git-specific version of `vc-state'."
-  ;; FIXME: This can't set 'ignored yet
+  ;; FIXME: This can't set 'ignored or 'conflict yet
+  ;; The 'ignored state could be detected with `git ls-files -i -o
+  ;; --exclude-standard` It also can't set 'needs-update or
+  ;; 'needs-merge. The rough equivalent would be that upstream branch
+  ;; for current branch is in fast-forward state i.e. current branch
+  ;; is direct ancestor of corresponding upstream branch, and the file
+  ;; was modified upstream.  But we can't check that without a network
+  ;; operation.
   (if (not (vc-git-registered file))
       'unregistered
     (vc-git--call nil "add" "--refresh" "--" (file-relative-name file))
diff --git a/lisp/vc-hooks.el b/lisp/vc-hooks.el
index 51f22791513..eb8b4e015a7 100644
--- a/lisp/vc-hooks.el
+++ b/lisp/vc-hooks.el
@@ -460,6 +460,9 @@ For registered files, the value returned is one of:
   'edited            The working file has been edited by the user.  If
                      locking is used for the file, this state means that
                      the current version is locked by the calling user.
+                     This status should *not* be reported for files 
+                     which have a changed mtime but the same content 
+                     as the repo copy.
 
   USER               The current version of the working file is locked by
                      some other USER (a string).