--- a/obsolete.py	Mon Aug 01 15:25:41 2011 +0200
+++ b/obsolete.py	Wed Sep 07 12:07:06 2011 +0200
@@ -14,6 +14,7 @@
 #############################
 
 def obsolete(ctx):
+    """is the changeset obsolete by other"""
     if ctx.node()is None:
         return False
     return boolean(ctx._repo.obsoleteby(ctx.node()))
@@ -31,7 +32,9 @@
 
 
 def cmddebugobsolete(ui, repo, subject, object):
-    """show enabled states"""
+    """Add an obsolete relation between a too node
+    
+    The subject is expected to be a newer version of the object"""
     sub = repo[subject]
     obj = repo[object]
     repo.addobsolete(sub.node(), obj.node())
@@ -45,25 +48,38 @@
 
         @util.propertycache
         def hiddenrevs(self):
+            # It's a property because It simpler that to handle the __init__
             revs = set()
             return revs
 
         @util.propertycache
         def _obsobjrels(self):
+            """{<old-node> -> set(<new-node>)}
+
+            also compute hidden revision"""
+            #reverse sub -> objs mapping
             objrels = {}
             for sub, objs in self._obssubrels.iteritems():
                 for obj in objs:
                     objrels.setdefault(obj, set()).add(sub)
+
+            # compute hidden (XXX should move elsewhere)
             for obj in objrels:
                 self.changelog.hiddenrevs.add(repo[obj].rev())
+
+            #
             return objrels
 
         @util.propertycache
         def _obssubrels(self):
+            """{<new-node> -> set(<old-node>)}"""
             return self._readobsrels()
 
 
+        ### Disk IO
         def _readobsrels(self):
+            """Write obsolete relation on disk"""
+            # XXX handle lock
             rels = {}
             try:
                 f = self.opener('obsolete-relations')
@@ -78,6 +94,8 @@
             return rels
 
         def _writeobsrels(self):
+            """Write obsolete relation on disk"""
+            # XXX handle lock
             f = self.opener('obsolete-relations', 'w', atomictemp=True)
             try:
                 for sub, objs in self._obssubrels.iteritems():
@@ -87,13 +105,15 @@
             finally:
                 f.close()
 
+        ### Public method
         def obsoletedby(self, node):
-            return self._readobsrels.get(node, set())
+            """return the set of node that make <node> obsolete (obj)"""
 
         def obsolete(self, node):
-            return self._readsubrels.get(node, set())
+            """return the set of node that <node> make obsolete (sub)"""
 
         def addobsolete(self, sub, obj):
+            """Add a relation marking that node <sub> is a new version of <obj>"""
             self._obssubrels.setdefault(sub, set()).add(obj)
             self._obsobjrels.setdefault(obj, set()).add(sub)
             self.changelog.hiddenrevs.add(repo[obj].rev())