[PATCH 3 of 3 V3] obsolete: flip `obstore.successors` and `obsolete.precursors`

[pierre-yves.david at logilab.fr]

# HG changeset patch
# User Pierre-Yves David <pierre-yves.david at logilab.fr>
# Date 1350394752 -7200
# Node ID 4fe705cf65de21a282f774ec8e135e7805520f6c
# Parent  599401a6fe6f44d33656f4c69f98de2f5ecec70c
obsolete: flip `obstore.successors` and `obsolete.precursors`

People were confused by the fact `obstore.precursors` contained marker allowing
to find "precursors" and vice-versa.

This changeset changes their meaning to:

- precursors[x] -> set(markers on precursors edges of x)
- successors[x] -> set(markers on successors edges of x)

Some documentation is added to clarify the situation.

diff --git a/mercurial/obsolete.py b/mercurial/obsolete.py
--- a/mercurial/obsolete.py
+++ b/mercurial/obsolete.py
@@ -18,10 +18,16 @@ transformations performed by history rew
 building new tools to reconciliate conflicting rewriting actions. To
 facilitate conflicts resolution, markers include various annotations
 besides old and news changeset identifiers, such as creation date or
 author name.
 
+The old obsoleted changeset is called "precursor" and possible replacements are
+called "successors".  Markers that used changeset X as a precursors are called
+"successor markers of X" because they hold information about the successors of
+X. Markers that use changeset Y as a successors are call "precursor markers of
+Y" because they hold information about the precursors of Y.
+
 Examples:
 
 - When changeset A is replacement by a changeset A', one marker is stored:
 
     (A, (A'))
@@ -179,12 +185,12 @@ class marker(object):
 
 class obsstore(object):
     """Store obsolete markers
 
     Markers can be accessed with two mappings:
-    - precursors: old -> set(new)
-    - successors: new -> set(old)
+    - precursors[x] -> set(markers on precursors edges of x)
+    - successors[x] -> set(markers on successors edges of x)
     """
 
     def __init__(self, sopener):
         # caches for various obsolescence related cache
         self.caches = {}
@@ -257,14 +263,14 @@ class obsstore(object):
 
     def _load(self, markers):
         for mark in markers:
             self._all.append(mark)
             pre, sucs = mark[:2]
-            self.precursors.setdefault(pre, set()).add(mark)
+            self.successors.setdefault(pre, set()).add(mark)
             for suc in sucs:
-                self.successors.setdefault(suc, set()).add(mark)
-        if node.nullid in self.successors:
+                self.precursors.setdefault(suc, set()).add(mark)
+        if node.nullid in self.precursors:
             raise util.Abort(_('bad obsolescence marker detected: '
                                'invalid successors nullid'))
 
 def _encodemarkers(markers, addheader=False):
     # Kept separate from flushmarkers(), it will be reused for
@@ -334,16 +340,16 @@ def allmarkers(repo):
     """all obsolete markers known in a repository"""
     for markerdata in repo.obsstore:
         yield marker(repo, markerdata)
 
 def precursormarkers(ctx):
-    """obsolete marker making this changeset obsolete"""
+    """obsolete marker marking this changeset as a successors"""
     for data in ctx._repo.obsstore.precursors.get(ctx.node(), ()):
         yield marker(ctx._repo, data)
 
 def successormarkers(ctx):
-    """obsolete marker marking this changeset as a successors"""
+    """obsolete marker making this changeset obsolete"""
     for data in ctx._repo.obsstore.successors.get(ctx.node(), ()):
         yield marker(ctx._repo, data)
 
 def anysuccessors(obsstore, node):
     """Yield every successor of <node>
@@ -352,11 +358,11 @@ def anysuccessors(obsstore, node):
     remaining = set([node])
     seen = set(remaining)
     while remaining:
         current = remaining.pop()
         yield current
-        for mark in obsstore.precursors.get(current, ()):
+        for mark in obsstore.successors.get(current, ()):
             for suc in mark[1]:
                 if suc not in seen:
                     seen.add(suc)
                     remaining.add(suc)
 
@@ -401,11 +407,11 @@ def clearobscaches(repo):
 @cachefor('obsolete')
 def _computeobsoleteset(repo):
     """the set of obsolete revisions"""
     obs = set()
     nm = repo.changelog.nodemap
-    for prec in repo.obsstore.precursors:
+    for prec in repo.obsstore.successors:
         rev = nm.get(prec)
         if rev is not None:
             obs.add(rev)
     return set(repo.revs('%ld - public()', obs))