--- a/hgext/obsolete.py	Tue Sep 13 20:24:44 2011 +0200
+++ b/hgext/obsolete.py	Tue Sep 13 21:15:31 2011 +0200
@@ -5,6 +5,68 @@
 #
 # This software may be used and distributed according to the terms of the
 # GNU General Public License version 2 or any later version.
+"""Introduce the Obsolete concept to mercurial
+
+General concept
+===============
+
+This extension introduces the *obsolete* concept. It adds a new *obsolete*
+relation between two changesets. A relation ``<changeset B> obsolete <changeset
+A>`` is set to denote that ``<changeset B>`` is new version of ``<changeset
+A>``.
+
+The *obsolete* relation act as a **perpendicular history** to the standard
+changeset history. Standard changeset history versions files. The *obsolete*
+relation versions changesets.
+
+:obsolete:     a changeset that have been replace by another one.
+:out of sync:  a non-obsolet changeset based on another one.
+:suspended:    an obsolete changeset with out of sync descendant.
+
+
+
+Usage and Feature
+=================
+
+
+Display and Exchange
+....................
+
+obsolete changesets are hidden. (except if they have non obsolete changeset)
+
+obsolete changesets are currently not exchange. This will probably change later
+but it was the simpler solution for now.
+
+New commands
+............
+
+a ``debugobsolete`` command has been added.
+
+It add an obsolete relation between too relation.
+
+Context object
+..............
+
+Context gain a ``obsolete`` method that return True if a changeset is obsolete
+False otherwise.
+
+revset
+......
+
+Add an ``obsolete()`` entry.
+
+To Do
+-----
+
+* refuse to obsolete published changesets
+
+* handle split
+
+* handle conflict
+
+* handle out of sync
+
+"""
 import os
 try:
     from cStringIO import StringIO