--- a/hgext/obsolete.py	Wed Aug 08 13:51:10 2012 +0200
+++ b/hgext/obsolete.py	Wed Aug 08 15:40:09 2012 +0200
@@ -747,6 +747,11 @@
 ### Extending revset and template                                 ###
 #####################################################################
 
+# this section add several useful revset symbol not yet in core.
+# they are subject to changes
+
+### hidden revset is not in core yet
+
 @eh.revset('hidden')
 def revsethidden(repo, subset, x):
     """``hidden()``
@@ -755,8 +760,7 @@
     args = revset.getargs(x, 0, 0, 'hidden takes no argument')
     return [r for r in subset if r in repo.hiddenrevs]
 
-## troubles
-
+### XXX I'm not sure this revset is useful
 @eh.revset('suspended')
 def revsetsuspended(repo, subset, x):
     """``suspended()``
@@ -806,6 +810,7 @@
     return [r for r in subset if r in cs]
 
 ### template keywords
+# XXX it does not handle troubles well :-/
 
 @eh.templatekw('obsolete')
 def obsoletekw(repo, ctx, templ, **args):
@@ -826,16 +831,19 @@
 ### Various trouble warning                                       ###
 #####################################################################
 
-
+# This section take care of issue warning to the user when troubles appear
 
 @eh.wrapcommand("update")
 @eh.wrapcommand("pull")
 def wrapmayobsoletewc(origfn, ui, repo, *args, **opts):
+    """Warn that the working directory parent is an obsolete changeset"""
     res = origfn(ui, repo, *args, **opts)
     if repo['.'].obsolete():
         ui.warn(_('Working directory parent is obsolete\n'))
     return res
 
+# XXX this could wrap transaction code
+# XXX (but this is a bit a layer violation)
 @eh.wrapcommand("commit")
 @eh.wrapcommand("push")
 @eh.wrapcommand("pull")
@@ -866,6 +874,8 @@
 
 @eh.reposetup
 def _repostabilizesetup(ui, repo):
+    """Add a hint for "hg stabilize" when troubles make push fails
+    """
     if not repo.local():
         return
 
@@ -888,10 +898,16 @@
     repo.__class__ = stabilizerrepo
 
 #####################################################################
-### Other extension compat                                        ###
+### Core Other extension compat                                   ###
 #####################################################################
 
+# This section make official history rewritter create obsolete marker
+
+
 ### commit --amend
+# make commit --amend create obsolete marker
+#
+# The precursor is still strip from the repository.
 
 @eh.wrapfunction(cmdutil, 'amend')
 def wrapcmdutilamend(orig, ui, repo, commitfunc, old, *args, **kwargs):
@@ -916,6 +932,9 @@
     return new
 
 ### rebase
+#
+# - ignore obsolete changeset
+# - create obsolete marker *instead of* striping
 
 def buildstate(orig, repo, dest, rebaseset, *ags, **kws):
     """wrapper for rebase 's buildstate that exclude obsolete changeset"""
@@ -1049,7 +1068,9 @@
 def _obsdeserialise(flike):
     """read a file like object serialised with _obsserialise
 
-    this desierialize into a {subject -> objects} mapping"""
+    this desierialize into a {subject -> objects} mapping
+
+    this was the very first format ever."""
     rels = {}
     for line in flike:
         subhex, objhex = line.split()