diff-hl-mode: add comments

diff --git a/diff-hl.el b/diff-hl.el
index a2a8d38df5a93107ffd5548bba850cff0e09353f..c116a6e5b35e9c0980486bb16ddae6e1129f47ad 100644 (file)
--- a/diff-hl.el
+++ b/diff-hl.el
@@ -426,11 +426,20 @@ in the source file, or the last line of the hunk above it."
         (add-hook 'after-save-hook 'diff-hl-update nil t)\r
         (add-hook 'after-change-functions 'diff-hl-edit nil t)\r
         (add-hook (if vc-mode\r
+                      ;; Defer until the end of this hook, so that its\r
+                      ;; elements can modify the update behavior.\r
                       'diff-hl-mode-on-hook\r
+                    ;; If we're only opening the file now,\r
+                    ;; `vc-find-file-hook' likely hasn't run yet, so\r
+                    ;; let's wait until the state information is\r
+                    ;; saved, in order not to fetch it twice.\r
                     'find-file-hook)\r
                   'diff-hl-update t t)\r
         (add-hook 'vc-checkin-hook 'diff-hl-update nil t)\r
         (add-hook 'after-revert-hook 'diff-hl-update nil t)\r
+        ;; Magit does call `auto-revert-handler', but it usually\r
+        ;; doesn't do much, because `buffer-stale--default-function'\r
+        ;; doesn't care about changed VC state.\r
         (add-hook 'magit-revert-buffer-hook 'diff-hl-update nil t)\r
         (add-hook 'text-scale-mode-hook 'diff-hl-define-bitmaps nil t))\r
     (remove-hook 'after-save-hook 'diff-hl-update t)\r