# HG changeset patch
# User Pierre-Yves David <pierre-yves.david@fb.com>
# Date 2016-02-08 16:34:32
# Node ID 1fc7b53638715878abfd0eff175915fe0ee6a4b4
# Parent  96f8baddbd6a3832454438f2bec4e478089d8153

destutil: document various failure cases

We document what various conditional branch mean and clarify that they are
exclusive (since they all end up in with exception raised).

diff --git a/mercurial/destutil.py b/mercurial/destutil.py
--- a/mercurial/destutil.py
+++ b/mercurial/destutil.py
@@ -199,18 +199,28 @@ def _destmergebranch(repo):
     nbhs = [bh for bh in bheads if not repo[bh].bookmarks()]
 
     if parent not in bheads:
+        # Case A: working copy if not on a head.
+        #
+        # This is probably a user mistake We bailout pointing at 'hg update'
         if len(repo.heads()) <= 1:
             msg, hint = msgdestmerge['nootherheadsbehind']
         else:
             msg, hint = msgdestmerge['notatheads']
         raise error.Abort(msg, hint=hint)
-
-    if len(nbhs) > 2:
+    elif len(nbhs) > 2:
+        # Case B: There is more than 2 anonymous heads
+        #
+        # This means that there will be more than 1 candidate. This is
+        # ambiguous. We abort asking the user to pick as explicit destination
+        # instead.
         msg, hint = msgdestmerge['toomanyheads']
         msg %= (branch, len(bheads))
         raise error.Abort(msg, hint=hint)
-
-    if len(nbhs) <= 1:
+    elif len(nbhs) <= 1:
+        # Case B: There is no other anonymous head that the one we are one
+        #
+        # This means that there is no natural candidate to merge with.
+        # We abort, with various messages for various cases.
         if len(bheads) > 1:
             msg, hint = msgdestmerge['bookmarkedheads']
         elif len(repo.heads()) > 1:
@@ -219,8 +229,7 @@ def _destmergebranch(repo):
         else:
             msg, hint = msgdestmerge['nootherheads']
         raise error.Abort(msg, hint=hint)
-
-    if parent == nbhs[0]:
+    elif parent == nbhs[0]:
         node = nbhs[-1]
     else:
         node = nbhs[0]