doc update

-"""SNAKES is the Net Algebra Kit for Editors and Simulators
-
-SNAKES is a Python library allowing to model all sorts of Petri nets
-and to execute them. It is very general as most Petri nets annotations
-can be arbitrary Python expressions while most values can be arbitrary
-Python objects.
-
-SNAKES can be further extended with plugins, several ones being
-already provided, in particular two plugins implement the Petri nets
-compositions defined for the Petri Box Calculus and its successors.
+"""SNAKES library is organised into three parts:
+
+  * the core library is package `snakes` and its modules, among which
+    `snakes.nets` is the one to work with Petri nets while the others
+    can be seen as auxiliary modules
+  * the plugin system and the plugins themselves reside into package
+    `snakes.plugins`
+  * auxiliary tools are kept into other sub-packages: `snakes.lang`
+    for all the material related to parsing Python and other
+    languages, `snakes.utils` for various utilities like the ABCD
+    compiler
 
 
 @author: Franck Pommereau
 @author: Franck Pommereau
 @organization: University of Evry/Paris-Saclay
 @organization: University of Evry/Paris-Saclay
 @copyright: (C) 2005-2013 Franck Pommereau
 @copyright: (C) 2005-2013 Franck Pommereau
 @license: GNU Lesser General Public Licence (aka. GNU LGPL), see the
 @license: GNU Lesser General Public Licence (aka. GNU LGPL), see the
-    file `doc/COPYING` in the distribution or visit [the GNU web
+    file `doc/COPYING` in the distribution or visit the [GNU web
     site](http://www.gnu.org/licenses/licenses.html#LGPL)
     site](http://www.gnu.org/licenses/licenses.html#LGPL)
 @contact: franck.pommereau@ibisc.univ-evry.fr
 @contact: franck.pommereau@ibisc.univ-evry.fr
 """
 """
@@ -21,8 +22,13 @@ compositions defined for the Petri Box Calculus and its successors.
 version = "0.9.16"
 version = "0.9.16"
 defaultencoding = "utf-8"
 defaultencoding = "utf-8"
 
 
+"""## Module `snakes`
+
+This module only provides the exceptions used throughout SNAKES.
+"""
+
 class SnakesError (Exception) :
 class SnakesError (Exception) :
-    "An error in SNAKES"
+    "Generic error in SNAKES"
     pass
     pass
 
 
 class ConstraintError (SnakesError) :
 class ConstraintError (SnakesError) :

-"""Basic data types and functions used in SNAKES
+"""Basic data types and related functions used in SNAKES
 """
 """
 
 
 import operator, inspect
 import operator, inspect
@@ -8,7 +8,8 @@ from snakes.hashables import hdict
 from snakes.pnml import Tree
 from snakes.pnml import Tree
 
 
 def cross (sets) :
 def cross (sets) :
-    """Cross-product.
+    """Cross-product of some iterable collections (typically, `list`
+    or `set`).
 
 
     >>> list(cross([[1, 2], [3, 4, 5]]))
     >>> list(cross([[1, 2], [3, 4, 5]]))
     [(1, 3), (1, 4), (1, 5), (2, 3), (2, 4), (2, 5)]
     [(1, 3), (1, 4), (1, 5), (2, 3), (2, 4), (2, 5)]
@@ -21,10 +22,9 @@ def cross (sets) :
     []
     []
 
 
     @param sets: the sets of values to use
     @param sets: the sets of values to use
-    @type sets: `iterable(iterable(object))`
-    @return: the `list` of obtained tuples (lists are used to allow
-        unhashable objects)
-    @rtype: `generator(tuple(object))`
+    @type sets: `iterable`
+    @return: an iterator over the tuples in the cross-product
+    @rtype: `generator`
     """
     """
     if len(sets) == 0 :
     if len(sets) == 0 :
         pass
         pass
@@ -65,8 +65,8 @@ def iterate (value) :
 class WordSet (set) :
 class WordSet (set) :
     """A set of words being able to generate fresh words.
     """A set of words being able to generate fresh words.
     """
     """
-    def fresh (self, add=False, min=1, allowed="abcdefghijklmnopqrstuvwxyz",
-               base="") :
+    def fresh (self, add=False, min=1, base="",
+               allowed="abcdefghijklmnopqrstuvwxyz") :
         """Create a fresh word (ie, which is not in the set).
         """Create a fresh word (ie, which is not in the set).
 
 
         >>> w = WordSet(['foo', 'bar'])
         >>> w = WordSet(['foo', 'bar'])
@@ -87,6 +87,8 @@ class WordSet (set) :
         @type min: `int`
         @type min: `int`
         @param allowed: characters allowed in the new word
         @param allowed: characters allowed in the new word
         @type allowed: `str`
         @type allowed: `str`
+        @param base: prefix of generated words
+        @type base: `str`
         """
         """
         if base :
         if base :
             result = [base] + [allowed[0]] * max(0, min - len(base))
             result = [base] + [allowed[0]] * max(0, min - len(base))
@@ -118,7 +120,7 @@ class MultiSet (hdict) :
 
 
     MultiSets support various operations, in particular: addition
     MultiSets support various operations, in particular: addition
     (`+`), substraction (`-`), multiplication by a non negative
     (`+`), substraction (`-`), multiplication by a non negative
-    integer (`*k`), comparisons (`<`, `>`, etc.), length (`len`)
+    integer (`*k`), comparisons (`<`, `>`, etc.), length (`len`).
     """
     """
     def __init__ (self, values=[]) :
     def __init__ (self, values=[]) :
         """Initialise the multiset, adding values to it.
         """Initialise the multiset, adding values to it.
@@ -128,17 +130,18 @@ class MultiSet (hdict) :
         >>> MultiSet()
         >>> MultiSet()
         MultiSet([])
         MultiSet([])
 
 
-        @param values: a single value or an iterable object holding
+        @param values: a single value or an iterable collection of
             values (strings are not iterated)
             values (strings are not iterated)
-        @type values: any atomic object (`str` included) or an
-            iterable object
+        @type values: `object`
         """
         """
         self.add(values)
         self.add(values)
     def copy (self) :
     def copy (self) :
         """Copy a `MultiSet`
         """Copy a `MultiSet`
 
 
-        >>> MultiSet([1, 2, 3, 1, 2]).copy()
-        MultiSet([...])
+        >>> m1 = MultiSet([1, 2, 3, 1, 2])
+        >>> m2 = m1.copy()
+        >>> m1 == m2 and m1 is not m2
+        True
 
 
         @return: a copy of the multiset
         @return: a copy of the multiset
         @rtype: `MultiSet`
         @rtype: `MultiSet`
@@ -147,6 +150,7 @@ class MultiSet (hdict) :
         result.update(self)
         result.update(self)
         return result
         return result
     __pnmltag__ = "multiset"
     __pnmltag__ = "multiset"
+    # apidoc skip
     def __pnmldump__ (self) :
     def __pnmldump__ (self) :
         """
         """
         >>> MultiSet([1, 2, 3, 4, 1, 2]).__pnmldump__()
         >>> MultiSet([1, 2, 3, 4, 1, 2]).__pnmldump__()
@@ -202,6 +206,7 @@ class MultiSet (hdict) :
                               Tree("value", None, Tree.from_obj(value)),
                               Tree("value", None, Tree.from_obj(value)),
                               Tree("multiplicity", str(self[value]))))
                               Tree("multiplicity", str(self[value]))))
         return Tree(self.__pnmltag__, None, *nodes)
         return Tree(self.__pnmltag__, None, *nodes)
+    # apidoc skip
     @classmethod
     @classmethod
     def __pnmlload__ (cls, tree) :
     def __pnmlload__ (cls, tree) :
         """Load a multiset from its PNML representation
         """Load a multiset from its PNML representation
@@ -220,9 +225,10 @@ class MultiSet (hdict) :
         """Add a single value `times` times.
         """Add a single value `times` times.
 
 
         @param value: the value to add
         @param value: the value to add
-        @type value: any object
+        @type value: `object`
         @param times: the number of times that `value` has to be added
         @param times: the number of times that `value` has to be added
         @type times: non negative `int`
         @type times: non negative `int`
+        @raise ValueError: when `times` is negative
         """
         """
         if times < 0 :
         if times < 0 :
             raise ValueError("negative values are forbidden")
             raise ValueError("negative values are forbidden")
@@ -242,10 +248,11 @@ class MultiSet (hdict) :
         [1, 1, 2, 2, 2, 2, 3, 3, 5, 5, 5]
         [1, 1, 2, 2, 2, 2, 3, 3, 5, 5, 5]
 
 
         @param values: the values to add or a single value to add
         @param values: the values to add or a single value to add
-        @type values: any atomic object (`str` included) or an
-            iterable object
+        @type values: `object`
         @param times: the number of times each value should be added
         @param times: the number of times each value should be added
-        @type times: non negative `int`
+            (must be non-negative)
+        @type times: `int`
+        @raise ValueError: when `times` is negative
         """
         """
         self.__mutable__()
         self.__mutable__()
         for value in iterate(values) :
         for value in iterate(values) :
@@ -258,6 +265,7 @@ class MultiSet (hdict) :
         @param times: the number of times that `value` has to be
         @param times: the number of times that `value` has to be
             removed
             removed
         @type times: non negative `int`
         @type times: non negative `int`
+        @raise ValueError: when `times` is negative
         """
         """
         if times < 0 :
         if times < 0 :
             raise ValueError("negative values are forbidden")
             raise ValueError("negative values are forbidden")
@@ -269,8 +277,7 @@ class MultiSet (hdict) :
     def remove (self, values, times=1) :
     def remove (self, values, times=1) :
         """Remove values to the multiset.
         """Remove values to the multiset.
 
 
-        >>> m = MultiSet()
-        >>> m.add([1, 2, 2, 3], 2)
+        >>> m = MultiSet([1, 2, 2, 3] * 2)
         >>> list(sorted(m.items()))
         >>> list(sorted(m.items()))
         [1, 1, 2, 2, 2, 2, 3, 3]
         [1, 1, 2, 2, 2, 2, 3, 3]
         >>> m.remove(2, 3)
         >>> m.remove(2, 3)
@@ -282,10 +289,11 @@ class MultiSet (hdict) :
 
 
         @param values: the values to remove or a single value to
         @param values: the values to remove or a single value to
             remove
             remove
-        @type values: any atomic object (`str` included) or an
-            iterable object
+        @type values: `object`
         @param times: the number of times each value should be removed
         @param times: the number of times each value should be removed
-        @type times: non negative `int`
+            (must be non negative)
+        @type times: `int`
+        @raise ValueError: when `times` is negative
         """
         """
         self.__mutable__()
         self.__mutable__()
         for value in iterate(values) :
         for value in iterate(values) :
@@ -303,22 +311,21 @@ class MultiSet (hdict) :
         """
         """
         return self.get(value, 0)
         return self.get(value, 0)
     def __iter__ (self) :
     def __iter__ (self) :
-        """Iterate over the values (with repetitions).
-        
-        Use `MultiSet.keys` to ignore repetitions.
+        """Iterate over the values, _including repetitions_. Use
+        `MultiSet.keys` to ignore repetitions.
 
 
         >>> list(sorted(iter(MultiSet([1, 2, 3, 1, 2]))))
         >>> list(sorted(iter(MultiSet([1, 2, 3, 1, 2]))))
         [1, 1, 2, 2, 3]
         [1, 1, 2, 2, 3]
 
 
         @return: an iterator on the elements
         @return: an iterator on the elements
-        @rtype: `iterator`
+        @rtype: `generator`
         """
         """
         for value in dict.__iter__(self) :
         for value in dict.__iter__(self) :
             for count in range(self[value]) :
             for count in range(self[value]) :
                 yield value
                 yield value
     def items (self) :
     def items (self) :
         """Return the list of items with repetitions. The list without
         """Return the list of items with repetitions. The list without
-        repetitions can be retrieved with the `key` method.
+        repetitions can be retrieved with `MultiSet.key`.
 
 
         >>> m = MultiSet([1, 2, 2, 3])
         >>> m = MultiSet([1, 2, 2, 3])
         >>> list(sorted(m.items()))
         >>> list(sorted(m.items()))
@@ -326,7 +333,7 @@ class MultiSet (hdict) :
         >>> list(sorted(m.keys()))
         >>> list(sorted(m.keys()))
         [1, 2, 3]
         [1, 2, 3]
 
 
-        @return: list of items with repetitions
+        @return: list of items including repetitions
         @rtype: `list`
         @rtype: `list`
         """
         """
         return list(iter(self))
         return list(iter(self))
@@ -352,7 +359,7 @@ class MultiSet (hdict) :
         """
         """
         return "MultiSet([%s])" % ", ".join(repr(x) for x in self)
         return "MultiSet([%s])" % ", ".join(repr(x) for x in self)
     def __len__ (self) :
     def __len__ (self) :
-        """Return the number of elements, including repetitions.
+        """Return the number of elements, _including repetitions_.
 
 
         >>> len(MultiSet([1, 2] * 3))
         >>> len(MultiSet([1, 2] * 3))
         6
         6
@@ -364,7 +371,7 @@ class MultiSet (hdict) :
         else :
         else :
             return reduce(operator.add, self.values())
             return reduce(operator.add, self.values())
     def size (self) :
     def size (self) :
-        """Return the number of elements, excluding repetitions.
+        """Return the number of elements, _excluding repetitions_.
 
 
         >>> MultiSet([1, 2] * 3).size()
         >>> MultiSet([1, 2] * 3).size()
         2
         2
@@ -387,7 +394,8 @@ class MultiSet (hdict) :
             result._add(value, times)
             result._add(value, times)
         return result
         return result
     def __sub__ (self, other) :
     def __sub__ (self, other) :
-        """Substract two multisets.
+        """Substract two multisets. The second multiset must be
+        smaller than the first one.
 
 
         >>> MultiSet([1, 2, 3]) - MultiSet([2, 3])
         >>> MultiSet([1, 2, 3]) - MultiSet([2, 3])
         MultiSet([1])
         MultiSet([1])
@@ -399,6 +407,7 @@ class MultiSet (hdict) :
         @param other: the multiset to substract
         @param other: the multiset to substract
         @type other: `MultiSet`
         @type other: `MultiSet`
         @rtype: `MultiSet`
         @rtype: `MultiSet`
+        @raise ValueError: when the second multiset is not smaller
         """
         """
         result = self.copy()
         result = self.copy()
         for value, times in dict.items(other) :
         for value, times in dict.items(other) :
@@ -407,12 +416,13 @@ class MultiSet (hdict) :
     def __mul__ (self, other) :
     def __mul__ (self, other) :
         """Multiplication by a non-negative integer.
         """Multiplication by a non-negative integer.
 
 
-        >>> MultiSet([1, 2]) * 3
-        MultiSet([...])
+        >>> MultiSet([1, 2]) * 3 == MultiSet([1, 2] * 3)
+        True
 
 
         @param other: the integer to multiply
         @param other: the integer to multiply
         @type other: non-negative `int`
         @type other: non-negative `int`
         @rtype: `MultiSet`
         @rtype: `MultiSet`
+        @raise ValueError: when `other` is negative
         """
         """
         if other < 0 :
         if other < 0 :
             raise ValueError("negative values are forbidden")
             raise ValueError("negative values are forbidden")
@@ -460,7 +470,9 @@ class MultiSet (hdict) :
         """
         """
         return not(self == other)
         return not(self == other)
     def __lt__ (self, other) :
     def __lt__ (self, other) :
-        """Test for strict inclusion.
+        """Test for strict inclusion. A multiset `A` is strictly
+        included in a multiset `B` iff every element in `A` is also in
+        `B` but less repetitions `A` than in `B`.
 
 
         >>> MultiSet([1, 2, 3]) < MultiSet([1, 2, 3, 4])
         >>> MultiSet([1, 2, 3]) < MultiSet([1, 2, 3, 4])
         True
         True
@@ -488,7 +500,7 @@ class MultiSet (hdict) :
                 result = True
                 result = True
         return result or (dict.__len__(self) < dict.__len__(other))
         return result or (dict.__len__(self) < dict.__len__(other))
     def __le__ (self, other) :
     def __le__ (self, other) :
-        """Test for inclusion inclusion.
+        """Test for inclusion.
 
 
         >>> MultiSet([1, 2, 3]) <= MultiSet([1, 2, 3, 4])
         >>> MultiSet([1, 2, 3]) <= MultiSet([1, 2, 3, 4])
         True
         True
@@ -551,7 +563,8 @@ class MultiSet (hdict) :
         """
         """
         return other.__le__(self)
         return other.__le__(self)
     def domain (self) :
     def domain (self) :
-        """Return the domain of the multiset
+        """Return the domain of the multiset, that is, the set of
+        elements that occurr at least once in the multiset.
 
 
         >>> list(sorted((MultiSet([1, 2, 3, 4]) + MultiSet([1, 2, 3])).domain()))
         >>> list(sorted((MultiSet([1, 2, 3, 4]) + MultiSet([1, 2, 3])).domain()))
         [1, 2, 3, 4]
         [1, 2, 3, 4]
@@ -589,6 +602,7 @@ class Substitution (object) :
         Substitution(...)
         Substitution(...)
         """
         """
         self._dict = dict(*largs, **dargs)
         self._dict = dict(*largs, **dargs)
+    # apidoc skip
     def __hash__ (self) :
     def __hash__ (self) :
         """
         """
         >>> hash(Substitution(x=1, y=2)) == hash(Substitution(y=2, x=1))
         >>> hash(Substitution(x=1, y=2)) == hash(Substitution(y=2, x=1))
@@ -599,7 +613,8 @@ class Substitution (object) :
                       (hash(i) for i in self._dict.items()),
                       (hash(i) for i in self._dict.items()),
                       153913524)
                       153913524)
     def __eq__ (self, other) :
     def __eq__ (self, other) :
-        """
+        """Test for equality.
+
         >>> Substitution(x=1, y=2) == Substitution(y=2, x=1)
         >>> Substitution(x=1, y=2) == Substitution(y=2, x=1)
         True
         True
         >>> Substitution(x=1, y=2) == Substitution(y=1, x=1)
         >>> Substitution(x=1, y=2) == Substitution(y=1, x=1)
@@ -610,7 +625,8 @@ class Substitution (object) :
         except :
         except :
             return False
             return False
     def __ne__ (self, other) :
     def __ne__ (self, other) :
-        """
+        """Test for inequality.
+
         >>> Substitution(x=1, y=2) != Substitution(y=2, x=1)
         >>> Substitution(x=1, y=2) != Substitution(y=2, x=1)
         False
         False
         >>> Substitution(x=1, y=2) != Substitution(y=1, x=1)
         >>> Substitution(x=1, y=2) != Substitution(y=1, x=1)
@@ -618,6 +634,7 @@ class Substitution (object) :
         """
         """
         return not self.__eq__(other)
         return not self.__eq__(other)
     __pnmltag__ = "substitution"
     __pnmltag__ = "substitution"
+    # apidoc skip
     def __pnmldump__ (self) :
     def __pnmldump__ (self) :
         """Dumps a substitution to a PNML tree
         """Dumps a substitution to a PNML tree
 
 
@@ -658,6 +675,7 @@ class Substitution (object) :
                               Tree("value", None,
                               Tree("value", None,
                                    Tree.from_obj(value))))
                                    Tree.from_obj(value))))
         return Tree(self.__pnmltag__, None, *nodes)
         return Tree(self.__pnmltag__, None, *nodes)
+    # apidoc skip
     @classmethod
     @classmethod
     def __pnmlload__ (cls, tree) :
     def __pnmlload__ (cls, tree) :
         """Load a substitution from its PNML representation
         """Load a substitution from its PNML representation
@@ -678,7 +696,8 @@ class Substitution (object) :
             result._dict[name] = value
             result._dict[name] = value
         return result
         return result
     def items (self) :
     def items (self) :
-        """Return the list of pairs (name, value).
+        """Return the list of pairs `(name, value)` such that the
+        substitution maps each `name` to the correspondign `value`.
 
 
         >>> Substitution(x=1, y=2).items()
         >>> Substitution(x=1, y=2).items()
         [('...', ...), ('...', ...)]
         [('...', ...), ('...', ...)]
@@ -698,17 +717,17 @@ class Substitution (object) :
         """
         """
         return set(self._dict.keys())
         return set(self._dict.keys())
     def image (self) :
     def image (self) :
-        """Return the set of values associated to the names.
+        """Return the list of values associated to the names.
 
 
         >>> list(sorted(Substitution(x=1, y=2).image()))
         >>> list(sorted(Substitution(x=1, y=2).image()))
         [1, 2]
         [1, 2]
 
 
-        @return: the set of values associated to names
-        @rtype: `set`
+        @return: the list of values associated to names
+        @rtype: `list`
         """
         """
-        return set(self._dict.values())
+        return list(self._dict.values())
     def __contains__ (self, name) :
     def __contains__ (self, name) :
-        """Test if a name is mapped.
+        """Test if a name is mapped by the substitution.
 
 
         >>> 'x' in Substitution(x=1, y=2)
         >>> 'x' in Substitution(x=1, y=2)
         True
         True
@@ -758,8 +777,8 @@ class Substitution (object) :
     def dict (self) :
     def dict (self) :
         """Return the mapping as a dictionnary.
         """Return the mapping as a dictionnary.
 
 
-        >>> Substitution(x=1, y=2).dict()
-        {'...': ..., '...': ...}
+        >>> Substitution(x=1, y=2).dict() == {'x': 1, 'y': 2}
+        True
 
 
         @return: a dictionnary that does the same mapping as the
         @return: a dictionnary that does the same mapping as the
             substitution
             substitution
@@ -767,10 +786,12 @@ class Substitution (object) :
         """
         """
         return self._dict.copy()
         return self._dict.copy()
     def copy (self) :
     def copy (self) :
-        """Copy the mapping.
+        """Return a distinct copy of the mapping.
 
 
-        >>> Substitution(x=1, y=2).copy()
-        Substitution(...)
+        >>> s1 = Substitution(x=1, y=2)
+        >>> s2 = s1.copy()
+        >>> s1 == s2 and s1 is not s2
+        True
 
 
         @return: a copy of the substitution
         @return: a copy of the substitution
         @rtype: `Substitution`
         @rtype: `Substitution`
@@ -793,8 +814,6 @@ class Substitution (object) :
     def __getitem__ (self, var) :
     def __getitem__ (self, var) :
         """Return the mapped value.
         """Return the mapped value.
 
 
-        Fails with `DomainError` if `var` is not mapped.
-        
         >>> s = Substitution(x=1, y=2)
         >>> s = Substitution(x=1, y=2)
         >>> s['x']
         >>> s['x']
         1
         1
@@ -813,9 +832,8 @@ class Substitution (object) :
         except KeyError :
         except KeyError :
             raise DomainError("unbound variable '%s'" % var)
             raise DomainError("unbound variable '%s'" % var)
     def __call__ (self, var) :
     def __call__ (self, var) :
-        """Return the mapped value.
-        
-        Never fails but return `var` if it is not mapped.
+        """Return the mapped value or `var` itself if it is not
+        mapped.
 
 
         >>> s = Substitution(x=1, y=2)
         >>> s = Substitution(x=1, y=2)
         >>> s('x')
         >>> s('x')
@@ -835,7 +853,6 @@ class Substitution (object) :
             return var
             return var
     def __add__ (self, other) :
     def __add__ (self, other) :
         """Add two substitution.
         """Add two substitution.
-        
         Fails with `DomainError` if the two substitutions map a same
         Fails with `DomainError` if the two substitutions map a same
         name to different values.
         name to different values.
 
 
@@ -850,7 +867,7 @@ class Substitution (object) :
         @type other: `Substitution`
         @type other: `Substitution`
         @return: the union of the substitutions
         @return: the union of the substitutions
         @rtype: `Substitution`
         @rtype: `Substitution`
-        @raise DomainError: when one name is mapped to distinct values
+        @raise DomainError: when a name is inconsistently mapped
         """
         """
         for var in self :
         for var in self :
             if var in other and (self[var] != other[var]) :
             if var in other and (self[var] != other[var]) :
@@ -860,8 +877,8 @@ class Substitution (object) :
         return s
         return s
     def __mul__ (self, other) :
     def __mul__ (self, other) :
         """Compose two substitutions.
         """Compose two substitutions.
-        
-        The composition of f and g is such that (f*g)(x) = f(g(x)).
+        The composition of `f` and `g` is such that `(f*g)(x)` is
+        `f(g(x))`.
 
 
         >>> f = Substitution(a=1, d=3, y=5)
         >>> f = Substitution(a=1, d=3, y=5)
         >>> g = Substitution(b='d', c=2, e=4, y=6)
         >>> g = Substitution(b='d', c=2, e=4, y=6)
@@ -886,7 +903,8 @@ class Symbol (object) :
         """If `export` is `True`, the created symbol is exported under
         """If `export` is `True`, the created symbol is exported under
         its name. If `export` is `False`, no export is made. Finally,
         its name. If `export` is `False`, no export is made. Finally,
         if `export` is a string, it specifies the name of the exported
         if `export` is a string, it specifies the name of the exported
-        symbol.
+        symbol. Exporting the name is made by adding it to the
+        caller's global dict.
 
 
         @param name: the name (or value of the symbol)
         @param name: the name (or value of the symbol)
         @type name: `str`
         @type name: `str`
@@ -915,6 +933,7 @@ class Symbol (object) :
         if export :
         if export :
             inspect.stack()[1][0].f_globals[export] = self
             inspect.stack()[1][0].f_globals[export] = self
     __pnmltag__ = "symbol"
     __pnmltag__ = "symbol"
+    # apidoc skip
     def __pnmldump__ (self) :
     def __pnmldump__ (self) :
         """
         """
         >>> Symbol('egg', 'spam').__pnmldump__()
         >>> Symbol('egg', 'spam').__pnmldump__()
@@ -946,6 +965,7 @@ class Symbol (object) :
         else :
         else :
             children = [Tree.from_obj(self._export)]
             children = [Tree.from_obj(self._export)]
         return Tree(self.__pnmltag__, None, *children, **dict(name=self.name))
         return Tree(self.__pnmltag__, None, *children, **dict(name=self.name))
+    # apidoc skip
     @classmethod
     @classmethod
     def __pnmlload__ (cls, tree) :
     def __pnmlload__ (cls, tree) :
         """
         """
@@ -963,7 +983,9 @@ class Symbol (object) :
             export = name
             export = name
         return cls(name, export)
         return cls(name, export)
     def __eq__ (self, other) :
     def __eq__ (self, other) :
-        """
+        """Test for equality of two symbols, which is the equality of
+        their names.
+
         >>> Symbol('foo', 'bar') == Symbol('foo')
         >>> Symbol('foo', 'bar') == Symbol('foo')
         True
         True
         >>> Symbol('egg') == Symbol('spam')
         >>> Symbol('egg') == Symbol('spam')
@@ -975,13 +997,15 @@ class Symbol (object) :
         except AttributeError :
         except AttributeError :
             return False
             return False
     def __ne__ (self, other) :
     def __ne__ (self, other) :
-        """
+        """Test for inequality.
+
         >>> Symbol('foo', 'bar') != Symbol('foo')
         >>> Symbol('foo', 'bar') != Symbol('foo')
         False
         False
         >>> Symbol('egg') != Symbol('spam')
         >>> Symbol('egg') != Symbol('spam')
         True
         True
         """
         """
         return not (self == other)
         return not (self == other)
+    # apidoc skip
     def __hash__ (self) :
     def __hash__ (self) :
         """
         """
         >>> hash(Symbol('foo', 'bar')) == hash(Symbol('foo'))
         >>> hash(Symbol('foo', 'bar')) == hash(Symbol('foo'))
@@ -989,13 +1013,15 @@ class Symbol (object) :
         """
         """
         return hash((self.__class__.__name__, self.name))
         return hash((self.__class__.__name__, self.name))
     def __str__ (self) :
     def __str__ (self) :
-        """
+        """Short string representation
+
         >>> str(Symbol('foo'))
         >>> str(Symbol('foo'))
         'foo'
         'foo'
         """
         """
         return self.name
         return self.name
     def __repr__ (self) :
     def __repr__ (self) :
-        """
+        """String representation suitable for `eval`
+
         >>> Symbol('foo')
         >>> Symbol('foo')
         Symbol('foo')
         Symbol('foo')
         >>> Symbol('egg', 'spam')
         >>> Symbol('egg', 'spam')

-"""Hashable mutable objets.
-
-This module proposes hashable version of the mutable containers
+"""This module proposes hashable version of the mutable containers
 `list`, `dict` and `set`, called respectively `hlist`, `hdict` and
 `list`, `dict` and `set`, called respectively `hlist`, `hdict` and
-`hset`. After one object has been hashed, it becomes not mutable and
-raises a ValueError if a method which changes the object (let call a
-_mutation_ such a method) is invoqued. The object can be then un-
-hashed by calling `unhash` on it so that it becomes mutable again.
+`hset`.
+
+After one object has been hashed, it becomes not mutable and raises a
+`ValueError` if a method which changes the object (let call a
+_mutation_ such a method) is invoqued. The object can be then
+un-hashed by calling `unhash` on it so that it becomes mutable again.
 Notice that this may cause troubles if the object is stored in a set
 Notice that this may cause troubles if the object is stored in a set
 or dict which uses its hashcode to locate it. Notice also that
 or dict which uses its hashcode to locate it. Notice also that
 hashable containers cannot be hashed if they contain non hashable
 hashable containers cannot be hashed if they contain non hashable
@@ -53,7 +53,8 @@ from operator import xor
 from snakes.compat import *
 from snakes.compat import *
 
 
 def unhash (obj) :
 def unhash (obj) :
-    """Make the object hashable again.
+    """Make the object mutable again. This should be used with
+    caution, especially if the object is stored in a dict or a set.
 
 
     >>> l = hlist(range(3))
     >>> l = hlist(range(3))
     >>> _ = hash(l)
     >>> _ = hash(l)
@@ -72,6 +73,7 @@ def unhash (obj) :
     except :
     except :
         pass
         pass
 
 
+# apidoc skip
 def hashable (cls) :
 def hashable (cls) :
     """Wrap methods in a class in order to make it hashable.
     """Wrap methods in a class in order to make it hashable.
     """
     """
@@ -122,7 +124,7 @@ def hashable (cls) :
     return cls
     return cls
 
 
 class hlist (list) :
 class hlist (list) :
-    """Hashable lists.
+    """Hashable lists. They support all standard methods from `list`.
 
 
     >>> l = hlist(range(5))
     >>> l = hlist(range(5))
     >>> l
     >>> l
@@ -138,6 +140,7 @@ class hlist (list) :
     >>> unhash(l)
     >>> unhash(l)
     >>> l.append(6)
     >>> l.append(6)
     """
     """
+    # apidoc stop
     def __add__ (self, other) :
     def __add__ (self, other) :
         return self.__class__(list.__add__(self, other))
         return self.__class__(list.__add__(self, other))
     def __delitem__ (self, item) :
     def __delitem__ (self, item) :
@@ -200,7 +203,8 @@ class hlist (list) :
 hlist = hashable(hlist)
 hlist = hashable(hlist)
 
 
 class hdict (dict) :
 class hdict (dict) :
-    """Hashable dictionnaries.
+    """Hashable dictionnaries. They support all standard methods from
+    `dict`.
 
 
     >>> l = hlist(range(5))
     >>> l = hlist(range(5))
     >>> d = hdict([(l, 0)])
     >>> d = hdict([(l, 0)])
@@ -229,6 +233,7 @@ class hdict (dict) :
     >>> d.pop(l)
     >>> d.pop(l)
     0
     0
     """
     """
+    # apidoc stop
     def __delitem__ (self, key) :
     def __delitem__ (self, key) :
         self.__mutable__()
         self.__mutable__()
         dict.__delitem__(self, key)
         dict.__delitem__(self, key)
@@ -271,7 +276,7 @@ class hdict (dict) :
 hdict = hashable(hdict)
 hdict = hashable(hdict)
 
 
 class hset (set) :
 class hset (set) :
-    """Hashable sets.
+    """Hashable sets. They support all standard methods from `set`.
 
 
     >>> s = hset()
     >>> s = hset()
     >>> l = hlist(range(5))
     >>> l = hlist(range(5))
@@ -298,6 +303,7 @@ class hset (set) :
     >>> unhash(s)
     >>> unhash(s)
     >>> s.discard(l)
     >>> s.discard(l)
     """
     """
+    # apidoc stop
     def __and__ (self, other) :
     def __and__ (self, other) :
         return self.__class__(set.__and__(self, other))
         return self.__class__(set.__and__(self, other))
     def __hash__ (self) :
     def __hash__ (self) :

+"""This package is dedicated to parse and work with various languages,
+in particular Python itself and ABCD. These are mainly utilities for
+internal use in SNAKES, however, they may be of general interest
+independently of SNAKES.
+
+@todo: add documentation about how to use parsing and similar services
+"""
+
 import sys
 import sys
 if sys.version_info[:2] in ((2, 6), (2, 7)) :
 if sys.version_info[:2] in ((2, 6), (2, 7)) :
     import ast
     import ast
@@ -14,9 +22,34 @@ else :
 
 
 sys.modules["snkast"] = ast
 sys.modules["snkast"] = ast
 
 
+"""### Module `ast` ###
+
+The module `ast` exported by `snakes.lang` is similar to Python's
+standard `ast` module (starting from version 2.6) but is available and
+uniform on every implementation of Python supported by SNAKES: CPython
+from 2.5, Jython and PyPy. (In general, these modules are available in
+these implementation - except CPython 2.5 - but with slight
+differences, so using `snakes.lang.ast` can be seen as a portable
+implementation.)
+
+Notice that this module is _not_ available for direct import but is
+exposed as a member of `snakes.lang`. Moreover, when `snakes.lang` is
+loaded, this module `ast` is also loaded as `snkast` in `sys.modules`,
+this allows to have both versions from Python and SNAKES
+simultaneously.
+
+>>> import snakes.lang.ast as ast
+ImportError ...
+ ...
+ImportError: No module named ast
+>>> from snakes.lang import ast
+>>> import snkast
+"""
+
 from . import unparse as _unparse
 from . import unparse as _unparse
 from snakes.compat import *
 from snakes.compat import *
 
 
+# apidoc skip
 class Names (ast.NodeVisitor) :
 class Names (ast.NodeVisitor) :
     def __init__ (self) :
     def __init__ (self) :
         ast.NodeVisitor.__init__(self)
         ast.NodeVisitor.__init__(self)
@@ -25,16 +58,24 @@ class Names (ast.NodeVisitor) :
         self.names.add(node.id)
         self.names.add(node.id)
 
 
 def getvars (expr) :
 def getvars (expr) :
-    """
+    """Return the set of variables (or names in general) involved in a
+    Python expression.
+
     >>> list(sorted(getvars('x+y<z')))
     >>> list(sorted(getvars('x+y<z')))
     ['x', 'y', 'z']
     ['x', 'y', 'z']
     >>> list(sorted(getvars('x+y<z+f(3,t)')))
     >>> list(sorted(getvars('x+y<z+f(3,t)')))
     ['f', 't', 'x', 'y', 'z']
     ['f', 't', 'x', 'y', 'z']
+
+    @param expr: a Python expression
+    @type expr: `str`
+    @return: the set of variable names as strings
+    @rtype: `set`
     """
     """
     names = Names()
     names = Names()
     names.visit(ast.parse(expr))
     names.visit(ast.parse(expr))
     return names.names - set(['None', 'True', 'False'])
     return names.names - set(['None', 'True', 'False'])
 
 
+# apidoc skip
 class Unparser(_unparse.Unparser) :
 class Unparser(_unparse.Unparser) :
     boolops = {"And": 'and', "Or": 'or'}
     boolops = {"And": 'and', "Or": 'or'}
     def _Interactive (self, tree) :
     def _Interactive (self, tree) :
@@ -58,11 +99,13 @@ class Unparser(_unparse.Unparser) :
         self.dispatch(tree.body)
         self.dispatch(tree.body)
         self.leave()
         self.leave()
 
 
+# apidoc skip
 def unparse (st) :
 def unparse (st) :
     output = io.StringIO()
     output = io.StringIO()
     Unparser(st, output)
     Unparser(st, output)
     return output.getvalue().strip()
     return output.getvalue().strip()
 
 
+# apidoc skip
 class Renamer (ast.NodeTransformer) :
 class Renamer (ast.NodeTransformer) :
     def __init__ (self, map_names) :
     def __init__ (self, map_names) :
         ast.NodeTransformer.__init__(self)
         ast.NodeTransformer.__init__(self)
@@ -96,7 +139,8 @@ class Renamer (ast.NodeTransformer) :
                                           ctx=ast.Load()), node)
                                           ctx=ast.Load()), node)
 
 
 def rename (expr, map={}, **ren) :
 def rename (expr, map={}, **ren) :
-    """
+    """Rename variables (ie, names) in a Python expression
+
     >>> rename('x+y<z', x='t')
     >>> rename('x+y<z', x='t')
     '((t + y) < z)'
     '((t + y) < z)'
     >>> rename('x+y<z+f(3,t)', f='g', t='z', z='t')
     >>> rename('x+y<z+f(3,t)', f='g', t='z', z='t')
@@ -105,12 +149,22 @@ def rename (expr, map={}, **ren) :
     '[(x + y) for x in range(3)]'
     '[(x + y) for x in range(3)]'
     >>> rename('[x+y for x in range(3)]', y='z')
     >>> rename('[x+y for x in range(3)]', y='z')
     '[(x + z) for x in range(3)]'
     '[(x + z) for x in range(3)]'
+
+    @param expr: a Python expression
+    @type expr: `str`
+    @param map: a mapping from old to new names (`str` to `str`)
+    @type map: `dict`
+    @param ren: additional mapping of old to new names
+    @type ren: `str`
+    @return: the new expression
+    @rtype: `str`
     """
     """
     map_names = dict(map)
     map_names = dict(map)
     map_names.update(ren)
     map_names.update(ren)
     transf = Renamer(map_names)
     transf = Renamer(map_names)
     return unparse(transf.visit(ast.parse(expr)))
     return unparse(transf.visit(ast.parse(expr)))
 
 
+# apidoc skip
 class Binder (Renamer) :
 class Binder (Renamer) :
     def visit_Name (self, node) :
     def visit_Name (self, node) :
         if node.id in self.map[-1] :
         if node.id in self.map[-1] :
@@ -119,7 +173,10 @@ class Binder (Renamer) :
             return node
             return node
 
 
 def bind (expr, map={}, **ren) :
 def bind (expr, map={}, **ren) :
-    """
+    """Replace variables (ie, names) in an expression with other
+    expressions. The replacements should be provided as `ast` nodes,
+    and so could be arbitrary expression.
+
     >>> bind('x+y<z', x=ast.Num(n=2))
     >>> bind('x+y<z', x=ast.Num(n=2))
     '((2 + y) < z)'
     '((2 + y) < z)'
     >>> bind('x+y<z', y=ast.Num(n=2))
     >>> bind('x+y<z', y=ast.Num(n=2))
@@ -128,6 +185,15 @@ def bind (expr, map={}, **ren) :
     '[(x + y) for x in range(3)]'
     '[(x + y) for x in range(3)]'
     >>> bind('[x+y for x in range(3)]', y=ast.Num(n=2))
     >>> bind('[x+y for x in range(3)]', y=ast.Num(n=2))
     '[(x + 2) for x in range(3)]'
     '[(x + 2) for x in range(3)]'
+
+    @param expr: a Python expression
+    @type expr: `str`
+    @param map: a mapping from old to new names (`str` to `ast.AST`)
+    @type map: `dict`
+    @param ren: additional mapping of old to new names
+    @type ren: `ast.AST`
+    @return: the new expression
+    @rtype: `str`
     """
     """
     map_names = dict(map)
     map_names = dict(map)
     map_names.update(ren)
     map_names.update(ren)

@@ -2,6 +2,8 @@
 
 
 This module holds the various Petri net elements: arcs, places,
 This module holds the various Petri net elements: arcs, places,
 transitions, markings, nets themselves and marking graphs.
 transitions, markings, nets themselves and marking graphs.
+
+@todo: revise documentation
 """
 """
 
 
 import re, operator, inspect
 import re, operator, inspect

-"""A plugins system.
+"""This package implements SNAKES plugin system. SNAKES plugins
+themselves are available as modules within the package.
+
+Examples below are based on plugin `hello` that is distributed with
+SNAKES to be used as an exemple of how to build a plugin. It extends
+class `PetriNet` adding a method `hello` that says hello displaying
+the name of the net.
+
+## Loading plugins ##
 
 
 The first example shows how to load a plugin: we load
 The first example shows how to load a plugin: we load
 `snakes.plugins.hello` and plug it into `snakes.nets`, which results
 `snakes.plugins.hello` and plug it into `snakes.nets`, which results
-in a new module that actually `snakes.nets` extended by
+in a new module that is actually `snakes.nets` extended by
 `snakes.plugins.hello`.
 `snakes.plugins.hello`.
 
 
 >>> import snakes.plugins as plugins
 >>> import snakes.plugins as plugins
@@ -18,11 +26,6 @@ The next example shows how to simulate the effect of `import module`:
 we give to `load` a thrid argument that is the name of the created
 we give to `load` a thrid argument that is the name of the created
 module, from which it becomes possible to import names or `*`.
 module, from which it becomes possible to import names or `*`.
 
 
-**Warning:** this feature will not work `load` is not called from the
-module where we then do the `from ... import ...`. This is exactly the
-same when, from a module `foo` that you load a module `bar`: if `bar`
-loads other modules they will not be imported in `foo`.
-
 >>> plugins.load('hello', 'snakes.nets', 'another_version')
 >>> plugins.load('hello', 'snakes.nets', 'another_version')
 <module ...>
 <module ...>
 >>> from another_version import PetriNet
 >>> from another_version import PetriNet
@@ -33,12 +36,23 @@ Hello from another net
 >>> n.hello()
 >>> n.hello()
 Hi, this is yet another net!
 Hi, this is yet another net!
 
 
-How to define a plugin is explained in the example `hello`.
+The last example shows how to load several plugins at once, instead of
+giving one plugin name, we just need to give a list of plugin names.
+
+>>> plugins.load(['hello', 'pos'], 'snakes.nets', 'mynets')
+<module ...>
+>>> from mynets import PetriNet
+>>> n = PetriNet('a net')
+>>> n.hello()  # works thanks to plugin `hello`
+Hello from a net
+>>> n.bbox()   # works thanks to plugin `pos`
+((0, 0), (0, 0))
 """
 """
 
 
 import imp, sys, inspect
 import imp, sys, inspect
 from functools import wraps
 from functools import wraps
 
 
+# apidoc skip
 def update (module, objects) :
 def update (module, objects) :
     """Update a module content
     """Update a module content
     """
     """
@@ -54,48 +68,17 @@ def update (module, objects) :
         else :
         else :
             raise ValueError("cannot plug '%r'" % obj)
             raise ValueError("cannot plug '%r'" % obj)
 
 
-def build (name, module, *objects) :
-    """Builds an extended module.
-    
-    The parameter `module` is exactly that taken by the function
-    `extend` of a plugin. This list argument `objects` holds all the
-    objects, constructed in `extend`, that are extensions of objects
-    from `module`. The resulting value should be returned by `extend`.
-    
-    @param name: the name of the constructed module
-    @type name: `str`
-    @param module: the extended module
-    @type module: `module`
-    @param objects: the sub-objects
-    @type objects: each is a class object
-    @return: the new module
-    @rtype: `module`
-    """
-    result = imp.new_module(name)
-    result.__dict__.update(module.__dict__)
-    update(result, objects)
-    result.__plugins__ = (module.__dict__.get("__plugins__",
-                                              (module.__name__,))
-                          + (name,))
-    for obj in objects :
-        if inspect.isclass(obj) :
-            obj.__plugins__ = result.__plugins__
-    return result
-
 def load (plugins, base, name=None) :
 def load (plugins, base, name=None) :
-    """Load plugins.
-    
-    `plugins` can be a single plugin name or module or a list of such
-    values. If `name` is not `None`, the extended module is loaded ad
-    `name` in `sys.modules` as well as in the global environment from
-    which `load` was called.
+    """Load plugins, `plugins` can be a single plugin name, a module
+    or a list of such values. If `name` is not `None`, the extended
+    module is loaded as `name` in `sys.modules` as well as in the
+    global environment from which `load` was called.
 
 
     @param plugins: the module that implements the plugin, or its
     @param plugins: the module that implements the plugin, or its
-        name, or a collection of such values
-    @type plugins: `str` or `module`, or a `list`/`tuple`/... of such
-        values
+        name, or a collection (eg, list, tuple) of such values
+    @type plugins: `object`
     @param base: the module being extended or its name
     @param base: the module being extended or its name
-    @type base: `str` or `module`
+    @type base: `object`
     @param name: the name of the created module
     @param name: the name of the created module
     @type name: `str`
     @type name: `str`
     @return: the extended module
     @return: the extended module
@@ -125,17 +108,45 @@ def load (plugins, base, name=None) :
         inspect.stack()[1][0].f_globals[name] = result
         inspect.stack()[1][0].f_globals[name] = result
     return result
     return result
 
 
+"""## Creating plugins ###
+
+We show now how to develop a plugin that allows instances of
+`PetriNet` to say hello: a new method `PetriNet.hello` is added and
+the constructor `PetriNet.__init__` is added a keyword argument
+`hello` for the message to print when calling method `hello`.
+
+Defining a plugins required to write a module with a function called
+`extend` that takes as its single argument the module to be extended.
+Inside this function, extensions of the classes in the module are
+defined as normal sub-classes. Function `extend` returns the extended
+classes. A decorator called `plugin` must be used, it also allows to
+resolve plugin dependencies and conflicts.
+"""
+
+# apidoc include "hello.py" lang="python"
+
+"""Note that, when extending an existing method like `__init__` above,
+we have to take care that you may be working on an already extended
+class, consequently, we cannot know how its arguments have been
+changed already. So, we must always use those from the unextended
+method plus `**args`. Then, we remove from the latter what your plugin
+needs and pass the remaining to the method of the base class if we
+need to call it (which is usually the case). """
+
 def plugin (base, depends=[], conflicts=[]) :
 def plugin (base, depends=[], conflicts=[]) :
     """Decorator for extension functions
     """Decorator for extension functions
 
 
-    @param base: name of base module (usually 'snakes.nets')
-    @type base: str
-    @param depends: list of plugins on which this one depends
-    @type depends: list of str
-    @param conflicts: list of plugins with which this one conflicts
-    @type conflicts: list of str
+    @param base: name of base module (usually 'snakes.nets') that the
+        plugin extends
+    @type base: `str`
+    @param depends: list of plugin names (as `str`) this one depends
+        on, prefix `snakes.plugins.` may be omitted
+    @type depends: `list`
+    @param conflicts: list of plugin names with which this one
+        conflicts
+    @type conflicts: `list`
     @return: the appropriate decorator
     @return: the appropriate decorator
-    @rtype: function
+    @rtype: `decorator`
     """
     """
     def wrapper (fun) :
     def wrapper (fun) :
         @wraps(fun)
         @wraps(fun)
@@ -164,9 +175,39 @@ def plugin (base, depends=[], conflicts=[]) :
         return extend
         return extend
     return wrapper
     return wrapper
 
 
+# apidoc skip
 def new_instance (cls, obj) :
 def new_instance (cls, obj) :
     """Create a copy of `obj` which is an instance of `cls`
     """Create a copy of `obj` which is an instance of `cls`
     """
     """
     result = object.__new__(cls)
     result = object.__new__(cls)
     result.__dict__.update(obj.__dict__)
     result.__dict__.update(obj.__dict__)
     return result
     return result
+
+# apidoc skip
+def build (name, module, *objects) :
+    """Builds an extended module.
+
+    The parameter `module` is exactly that taken by the function
+    `extend` of a plugin. This list argument `objects` holds all the
+    objects, constructed in `extend`, that are extensions of objects
+    from `module`. The resulting value should be returned by `extend`.
+
+    @param name: the name of the constructed module
+    @type name: `str`
+    @param module: the extended module
+    @type module: `module`
+    @param objects: the sub-objects
+    @type objects: each is a class object
+    @return: the new module
+    @rtype: `module`
+    """
+    result = imp.new_module(name)
+    result.__dict__.update(module.__dict__)
+    update(result, objects)
+    result.__plugins__ = (module.__dict__.get("__plugins__",
+                                              (module.__name__,))
+                          + (name,))
+    for obj in objects :
+        if inspect.isclass(obj) :
+            obj.__plugins__ = result.__plugins__
+    return result

+"""
+@todo: revise (actually make) documentation
+"""
+
 import snakes.plugins
 import snakes.plugins
 from snakes.plugins import new_instance
 from snakes.plugins import new_instance
 from snakes.pnml import Tree
 from snakes.pnml import Tree

@@ -26,6 +26,8 @@
 >>> n.layout()
 >>> n.layout()
 >>> any(node.pos == (-100, -100) for node in sorted(n.node(), key=str))
 >>> any(node.pos == (-100, -100) for node in sorted(n.node(), key=str))
 False
 False
+
+@todo: revise documentation
 """
 """
 
 
 import os, os.path, subprocess, collections
 import os, os.path, subprocess, collections

-"""An example plugin that allows instances class `PetriNet` to say hello.
-
-A new method `hello` is added. The constructor is added a keyword
-argument `hello` that must be the `str` to print when calling `hello`,
-with one `%s` that will be replaced by the name of the net when
-`hello` is called.
-
-Defining a plugins need writing a module with a single function called
-`extend` that takes a single argument that is the module to be
-extended.
-
-Inside the function, extensions of the classes in the module are
-defined as normal sub-classes.
-
-The function `extend` should return the extended module created by
-`snakes.plugins.build` that takes as arguments: the name of the
-extended module, the module taken as argument and the sub-classes
-defined (expected as a list argument `*args` in no special order).
-
-If the plugin depends on other plugins, for instance `foo` and `bar`,
-the function `extend` should be decorated by `@depends('foo', 'bar')`.
-
-Read the source code of this module to have an example
-"""
+"""An example plugin that allows instances of `PetriNet` to
+say hello. The source code can be used as a starting
+example."""
 
 
 import snakes.plugins
 import snakes.plugins
 
 
 @snakes.plugins.plugin("snakes.nets")
 @snakes.plugins.plugin("snakes.nets")
 def extend (module) :
 def extend (module) :
-    """Extends `module`
-    """
+    "Extends `module`"
     class PetriNet (module.PetriNet) :
     class PetriNet (module.PetriNet) :
-        """Extension of the class `PetriNet` in `module`
-        """
+        "Extension of the class `PetriNet` in `module`"
         def __init__ (self, name, **args) :
         def __init__ (self, name, **args) :
-            """When extending an existing method, take care that you may
-            be working on an already extended class, so you so not
-            know how its arguments have been changed. So, always use
-            those from the unextended class plus `**args`, remove from
-            it what your plugin needs and pass it to the method of the
-            extended class if you need to call it.
+            """Add new keyword argument `hello`
 
 
             >>> PetriNet('N').hello()
             >>> PetriNet('N').hello()
             Hello from N
             Hello from N
@@ -46,18 +18,13 @@ def extend (module) :
             Hi! This is N...
             Hi! This is N...
 
 
             @param args: plugin options
             @param args: plugin options
-            @keyword hello: the message to print, with `%s` where the
-                net name should appear.
+            @keyword hello: the message to print, with
+                `%s` where the net name should appear.
             @type hello: `str`
             @type hello: `str`
             """
             """
             self._hello = args.pop("hello", "Hello from %s")
             self._hello = args.pop("hello", "Hello from %s")
             module.PetriNet.__init__(self, name, **args)
             module.PetriNet.__init__(self, name, **args)
         def hello (self) :
         def hello (self) :
-            """A new method `hello`
-            
-            >>> n = PetriNet('N')
-            >>> n.hello()
-            Hello from N
-            """
+            "Ask the net to say hello"
             print(self._hello % self.name)
             print(self._hello % self.name)
     return PetriNet
     return PetriNet

 """A plugin to add labels to nodes and nets.
 """A plugin to add labels to nodes and nets.
+
+@todo: revise (actually make) documentation
 """
 """
 
 
 from snakes.plugins import plugin, new_instance
 from snakes.plugins import plugin, new_instance

@@ -65,6 +65,8 @@ Buffer('buffer')
 (1, 2)
 (1, 2)
 >>> n._declare
 >>> n._declare
 ['global x; x=1']
 ['global x; x=1']
+
+@todo: revise documentation
 """
 """
 
 
 import snakes.plugins
 import snakes.plugins

@@ -42,6 +42,8 @@ Position(1, 3)
 >>> n.transpose()
 >>> n.transpose()
 >>> n.node('t01').pos
 >>> n.node('t01').pos
 Position(-3, 1)
 Position(-3, 1)
+
+@todo: revise documentation
 """
 """
 
 
 from snakes import SnakesError
 from snakes import SnakesError

+"""
+@todo: revise (actually make) documentation
+"""
+
 from snakes.plugins import plugin
 from snakes.plugins import plugin
 from snakes.pnml import Tree, loads, dumps
 from snakes.pnml import Tree, loads, dumps
 import imp, sys, socket, traceback, operator
 import imp, sys, socket, traceback, operator

@@ -12,6 +12,8 @@ Several status are defined by default: `entry`, `internal`, `exit`,
 >>> n.add_place(Place('p1'), status=status.entry)
 >>> n.add_place(Place('p1'), status=status.entry)
 >>> n.place('p1')
 >>> n.place('p1')
 Place('p1', MultiSet([]), tAll, status=Status('entry'))
 Place('p1', MultiSet([]), tAll, status=Status('entry'))
+
+@todo: revise documentation
 """
 """
 
 
 import operator, weakref
 import operator, weakref

@@ -6,8 +6,6 @@ The plugin proposes a generalisation of the M-nets synchronisation in
 that it does not impose a fixed correspondence between action names
 that it does not impose a fixed correspondence between action names
 and action arities.
 and action arities.
 
 
-
-
   * class `Action` corresponds to a synchronisable action, it has a
   * class `Action` corresponds to a synchronisable action, it has a
     name, a send/receive flag and a list of parameters. Actions have
     name, a send/receive flag and a list of parameters. Actions have
     no predetermined arities, only conjugated actions with the same
     no predetermined arities, only conjugated actions with the same
@@ -66,6 +64,8 @@ t2 z>0
 >>> [t.name for t in sorted(n.transition(), key=str)]
 >>> [t.name for t in sorted(n.transition(), key=str)]
 ["((t1{...}+t2{...})[a(...)]{...}+t2{...})[a(...)]",
 ["((t1{...}+t2{...})[a(...)]{...}+t2{...})[a(...)]",
  "((t1{...}+t2{...})[a(...)]{...}+t2{...})[a(...)]"]
  "((t1{...}+t2{...})[a(...)]{...}+t2{...})[a(...)]"]
+
+@todo: revise documentation
 """
 """
 
 
 from snakes import ConstraintError
 from snakes import ConstraintError
@@ -91,6 +91,7 @@ class Action (object) :
         self.send = send
         self.send = send
         self.params = list(params)
         self.params = list(params)
     __pnmltag__ = "action"
     __pnmltag__ = "action"
+    # apidoc skip
     def __pnmldump__ (self) :
     def __pnmldump__ (self) :
         """
         """
         >>> Action('a', True, [Value(1), Variable('x')]).__pnmldump__()
         >>> Action('a', True, [Value(1), Variable('x')]).__pnmldump__()
@@ -114,6 +115,7 @@ class Action (object) :
         for param in self.params :
         for param in self.params :
             result.add_child(Tree.from_obj(param))
             result.add_child(Tree.from_obj(param))
         return result
         return result
+    # apidoc skip
     @classmethod
     @classmethod
     def __pnmlload__ (cls, tree) :
     def __pnmlload__ (cls, tree) :
         """
         """
@@ -136,6 +138,7 @@ class Action (object) :
             return "%s!(%s)" % (self.name, ",".join([str(p) for p in self]))
             return "%s!(%s)" % (self.name, ",".join([str(p) for p in self]))
         else :
         else :
             return "%s?(%s)" % (self.name, ",".join([str(p) for p in self]))
             return "%s?(%s)" % (self.name, ",".join([str(p) for p in self]))
+    # apidoc stop
     def __repr__ (self) :
     def __repr__ (self) :
         """
         """
         >>> a = Action('a', True, [Value(1), Variable('x')])
         >>> a = Action('a', True, [Value(1), Variable('x')])

@@ -3,6 +3,8 @@
 Petri nets objects are saved in PNML, other Python objects are saved
 Petri nets objects are saved in PNML, other Python objects are saved
 in a readable format when possible and pickled as a last solution.
 in a readable format when possible and pickled as a last solution.
 This should result in a complete PNML serialization of any object.
 This should result in a complete PNML serialization of any object.
+
+@todo: revise documentation
 """
 """
 
 
 import xml.dom.minidom
 import xml.dom.minidom

@@ -60,6 +60,8 @@ TypeError: ...
 Traceback (most recent call last):
 Traceback (most recent call last):
 ...
 ...
 TypeError: ...
 TypeError: ...
+
+@todo: revise documentation
 """
 """
 
 
 import inspect, sys
 import inspect, sys

+"""
+@todo: revise (actually make) documentation
+"""
+
 from snakes import SnakesError
 from snakes import SnakesError
 
 
 class CompilationError (SnakesError) :
 class CompilationError (SnakesError) :

+"""
+@todo: revise (actually make) documentation
+"""
+
 import sys, os, os.path
 import sys, os, os.path
-import inspect, fnmatch, collections
-import textwrap, doctest, ast
+import inspect, fnmatch, collections, re, shlex
+import textwrap, doctest
 import snakes
 import snakes
 from snakes.lang import unparse
 from snakes.lang import unparse
+from snakes.lang.python.parser import parse, ast
+
+try :
+    import markdown
+except :
+    markdown = None
 
 
 ##
 ##
 ## console messages
 ## console messages
@@ -62,6 +72,13 @@ class DocExtract (object) :
         self.out = None
         self.out = None
         self.exclude = exclude
         self.exclude = exclude
         self._last = "\n\n"
         self._last = "\n\n"
+    def md (self, text, inline=True) :
+        if markdown is None :
+            return text
+        elif inline :
+            return re.sub("</?p>", "\n", markdown.markdown(text), re.I)
+        else :
+            return markdown.markdown(text)
     def openout (self, path) :
     def openout (self, path) :
         if self.out is not None :
         if self.out is not None :
             self.out.close()
             self.out.close()
@@ -81,6 +98,10 @@ class DocExtract (object) :
             return False
             return False
         outdir = os.path.join(self.outpath, relpath)
         outdir = os.path.join(self.outpath, relpath)
         outpath = os.path.join(outdir, target)
         outpath = os.path.join(outdir, target)
+        if os.path.exists(outpath) :
+            if os.stat(path).st_mtime <= os.stat(outpath).st_mtime :
+                return False
+        self.inpath = path
         info("%s -> %r" % (self.module, outpath))
         info("%s -> %r" % (self.module, outpath))
         if not os.path.exists(outdir) :
         if not os.path.exists(outdir) :
             os.makedirs(outdir)
             os.makedirs(outdir)
@@ -114,56 +135,89 @@ class DocExtract (object) :
     def process (self) :
     def process (self) :
         for dirpath, dirnames, filenames in os.walk(self.path) :
         for dirpath, dirnames, filenames in os.walk(self.path) :
             for name in sorted(filenames) :
             for name in sorted(filenames) :
-                if not name.endswith(".py") :
+                if not name.endswith(".py") or name.startswith(".") :
                     continue
                     continue
                 path = os.path.join(dirpath, name)
                 path = os.path.join(dirpath, name)
                 if not self.openout(path) :
                 if not self.openout(path) :
                     continue
                     continue
-                node = ast.parse(open(path).read())
+                node = parse(open(path).read())
                 if ".plugins." in self.module :
                 if ".plugins." in self.module :
                     self.visit_plugin(node)
                     self.visit_plugin(node)
                 else :
                 else :
                     self.visit_module(node)
                     self.visit_module(node)
     def _pass (self, node) :
     def _pass (self, node) :
         pass
         pass
+    def directive (self, node) :
+        lines = node.st.text.lexer.lines
+        num = node.st.srow - 2
+        while num >= 0 and (not lines[num].strip()
+                            or lines[num].strip().startswith("@")) :
+            num -= 1
+        if num >= 0 and lines[num].strip().startswith("#") :
+            dirline = lines[num].lstrip("# \t").rstrip()
+            items = shlex.split(dirline)
+            if len(items) >= 2 and items[0].lower() == "apidoc" :
+                if len(items) == 2 and items[1].lower() in ("skip", "stop") :
+                    return items[1]
+                elif items[1].lower() == "include" :
+                    path = items[2]
+                    try :
+                        args = dict(i.split("=", 1) for i in items[3:])
+                    except :
+                        err("invalid directive %r (line %s)"
+                            % (dirline, num+1))
+                    self.write_include(path, **args)
+                else :
+                    err("unknown directive %r (line %s)"
+                        % (items[1], num+1))
+                    return None
+    def children (self, node) :
+        for child in ast.iter_child_nodes(node) :
+            directive = self.directive(child)
+            if directive == "skip" :
+                continue
+            elif directive == "stop" :
+                break
+            yield child
     def visit (self, node) :
     def visit (self, node) :
         name = getattr(node, "name", "__")
         name = getattr(node, "name", "__")
         if (name.startswith("_") and not (name.startswith("__")
         if (name.startswith("_") and not (name.startswith("__")
                                           and name.endswith("__"))) :
                                           and name.endswith("__"))) :
             return
             return
         try :
         try :
-            getattr(self, "visit_" + node.__class__.__name__, self._pass)(node)
+            getattr(self, "visit_" + node.__class__.__name__,
+                    self._pass)(node)
         except :
         except :
-            src = unparse(node)
+            src = node.st.source()
             if len(src) > 40 :
             if len(src) > 40 :
                 src = src[:40] + "..."
                 src = src[:40] + "..."
             err("line %s source %r" % (node.lineno, src))
             err("line %s source %r" % (node.lineno, src))
             raise
             raise
     def visit_module (self, node) :
     def visit_module (self, node) :
         self.write_module()
         self.write_module()
-        for child in ast.iter_child_nodes(node) :
+        for child in self.children(node) :
             self.visit(child)
             self.visit(child)
     def visit_plugin (self, node) :
     def visit_plugin (self, node) :
         self.write_module()
         self.write_module()
         extend = None
         extend = None
-        for child in ast.iter_child_nodes(node) :
+        for child in self.children(node) :
             if (getattr(child, "name", None) == "extend"
             if (getattr(child, "name", None) == "extend"
                 and isinstance(child, ast.FunctionDef)) :
                 and isinstance(child, ast.FunctionDef)) :
                 extend = child
                 extend = child
             else :
             else :
                 self.visit(child)
                 self.visit(child)
         self.write_plugin()
         self.write_plugin()
-        for child in ast.iter_child_nodes(extend) :
+        for child in self.children(extend) :
             self.visit(child)
             self.visit(child)
     def visit_ClassDef (self, node) :
     def visit_ClassDef (self, node) :
         self.write_class(node)
         self.write_class(node)
         self.classname = node.name
         self.classname = node.name
-        for child in ast.iter_child_nodes(node) :
+        for child in self.children(node) :
             self.visit(child)
             self.visit(child)
         self.classname = None
         self.classname = None
     def visit_FunctionDef (self, node) :
     def visit_FunctionDef (self, node) :
         self.write_function(node)
         self.write_function(node)
-        self.args = [n.id for n in node.args.args]
+        self.args = [n.arg for n in node.args.args]
         if self.args and self.args[0] == "self" :
         if self.args and self.args[0] == "self" :
             del self.args[0]
             del self.args[0]
         if node.args.vararg :
         if node.args.vararg :
@@ -193,26 +247,32 @@ class DocExtract (object) :
         else :
         else :
             self.writeline("### Function `%s` ###" % node.name)
             self.writeline("### Function `%s` ###" % node.name)
         self.newline()
         self.newline()
-        self.writeline("    :::python")
-        for line in unparse(node).splitlines() :
-            if line.startswith("def") :
-                self.writeline("    %s ..." % line)
-                break
-            else :
-                self.writeline("    " + line)
-        self.newline
+        self.write_def(node)
     def write_class (self, node) :
     def write_class (self, node) :
         self.newline()
         self.newline()
         self.writeline("### Class `%s` ###" % node.name)
         self.writeline("### Class `%s` ###" % node.name)
+        self.write_def(node)
+    def write_def (self, node) :
+        indent = node.st.scol
+        if node.st[0].symbol == "decorated" :
+            srow, scol = node.st[0][0][0][0].srow, node.st[0][0][0][0].scol
+            erow, ecol = node.st[0][1][-2].erow, node.st[0][1][-2].ecol
+        else :
+            srow, scol = node.st[0].srow, node.st[0].scol
+            erow, ecol = node.st[0][-2].erow, node.st[0][-2].ecol
+        lines = node.st.text.lexer.lines
+        if srow == erow :
+            source = [lines[srow-1][scol:ecol+1]]
+        else :
+            source = lines[srow-1:erow]
+            source[0] = source[0][scol:]
+            source[1:-1] = [s[indent:] for s in source[1:-1]]
+            source[-1] = source[-1][indent:ecol+1].rstrip() + " ..."
         self.newline()
         self.newline()
         self.writeline("    :::python")
         self.writeline("    :::python")
-        for line in unparse(node).splitlines() :
-            if line.startswith("class") :
-                self.writeline("    %s ..." % line)
-                break
-            else :
+        for line in source :
             self.writeline("    " + line)
             self.writeline("    " + line)
-        self.newline
+        self.newline()
     parse = doctest.DocTestParser().parse
     parse = doctest.DocTestParser().parse
     def write_doc (self, doc) :
     def write_doc (self, doc) :
         if doc is None :
         if doc is None :
@@ -240,7 +300,9 @@ class DocExtract (object) :
                     if not test :
                     if not test :
                         test = True
                         test = True
                         self.newline()
                         self.newline()
-                        self.writeline("    :::python")
+                        self.writetext("<!-- this comment avoids a bug in"
+                                       " Markdown parsing -->")
+                        self.writeline("    :::pycon")
                     for i, line in enumerate(doc.source.splitlines()) :
                     for i, line in enumerate(doc.source.splitlines()) :
                         if i > 0 :
                         if i > 0 :
                             self.writeline("    ... %s" % line)
                             self.writeline("    ... %s" % line)
@@ -281,65 +343,74 @@ class DocExtract (object) :
         if any(k in info for k in ("author", "organization", "copyright",
         if any(k in info for k in ("author", "organization", "copyright",
                                    "license", "contact")) :
                                    "license", "contact")) :
             self.newline()
             self.newline()
-            self.writeline('<div class="api-info">')
-            for tag in ("author", "organization", "copyright",
-                        "license", "contact") :
+            self.writeline('<ul id="api-info">')
+            for tag in ("author", "organization", "contact",
+                        "copyright", "license", ) :
                 if tag in info :
                 if tag in info :
-                    self.writeline('<div class="api-%s">' % tag)
+                    self.writeline('<li id="api-%s">' % tag)
                     self.writetext('<span class="api-title">%s:</span> %s'
                     self.writetext('<span class="api-title">%s:</span> %s'
-                                   % (tag.capitalize(), info[tag]),
+                                   % (tag.capitalize(),
+                                      self.md(info[tag])),
                                    subsequent_indent="  ")
                                    subsequent_indent="  ")
-                    self.writeline('</div>')
-            self.writeline('</div>')
+                    self.writeline('</li>')
+            self.writeline('</ul>')
         if any(info[k] for k in
         if any(info[k] for k in
                ("todo", "note", "attention", "bug", "warning")) :
                ("todo", "note", "attention", "bug", "warning")) :
             self.newline()
             self.newline()
-            self.writeline('<div class="api-remarks">')
-            self.writeline("##### Remarks #####")
-            self.newline()
+            self.writeline('<div id="api-remarks">')
             for tag in ("note", "todo", "attention", "bug", "warning") :
             for tag in ("note", "todo", "attention", "bug", "warning") :
                 for text in info[tag] :
                 for text in info[tag] :
                     self.writeline('<div class="api-%s">' % tag)
                     self.writeline('<div class="api-%s">' % tag)
                     self.writetext('<span class="api-title">%s:</span> %s'
                     self.writetext('<span class="api-title">%s:</span> %s'
-                                   % (tag.capitalize(), text),
+                                   % (tag.capitalize(), self.md(text)),
                                    subsequent_indent="  ")
                                    subsequent_indent="  ")
                     self.writeline('</div>')
                     self.writeline('</div>')
             self.writeline('</div>')
             self.writeline('</div>')
         if (any(info[k] for k in ("param", "type", "keyword"))
         if (any(info[k] for k in ("param", "type", "keyword"))
             or any(k in info for k in ("return", "rtype"))) :
             or any(k in info for k in ("return", "rtype"))) :
             self.newline()
             self.newline()
-            self.writeline('<div class="api-call">')
             self.writeline("##### Call API #####")
             self.writeline("##### Call API #####")
             self.newline()
             self.newline()
             for arg in self.args :
             for arg in self.args :
                 if arg in info["param"] :
                 if arg in info["param"] :
-                    self.writelist("`%s` (%s): %s"
-                                   % (arg,
-                                      info["type"].get(arg, "`object`"),
+                    self.writelist("`%s %s`: %s"
+                                   % (info["type"].get(arg, "object").strip("`"),
+                                      arg,
                                       info["param"][arg]))
                                       info["param"][arg]))
                 else :
                 else :
-                    self.writelist("`%s` (%s)"
-                                   % (arg,
-                                      info["type"].get(arg, "`object`")))
+                    self.writelist("`%s %s`"
+                                   % (info["type"].get(arg, "object").strip("`"),
+                                      arg))
             for kw, text in sorted(info["keyword"].items()) :
             for kw, text in sorted(info["keyword"].items()) :
                 self.writelist("`%s`: %s" % (kw, text))
                 self.writelist("`%s`: %s" % (kw, text))
             if any(k in info for k in ("return", "rtype")) :
             if any(k in info for k in ("return", "rtype")) :
                 if "return" in info :
                 if "return" in info :
-                    self.writelist("return %s: %s"
-                                   % (info.get("rtype", "`object`"),
+                    self.writelist("`return %s`: %s"
+                                   % (info.get("rtype", "object").strip("`"),
                                       info["return"]))
                                       info["return"]))
                 else :
                 else :
-                    self.writelist("return %s"
-                                   % (info.get("rtype", "`object`")))
-            self.writeline('</div>')
+                    self.writelist("`return %s`"
+                                   % (info.get("rtype", "object").strip("`")))
         if info["raise"] :
         if info["raise"] :
             self.newline()
             self.newline()
-            self.writeline('<div class="api-errors">')
             self.writeline("##### Exceptions #####")
             self.writeline("##### Exceptions #####")
             self.newline()
             self.newline()
             for exc, reason in sorted(info["raise"].items()) :
             for exc, reason in sorted(info["raise"].items()) :
                 self.writelist("`%s`: %s" % (exc, reason))
                 self.writelist("`%s`: %s" % (exc, reason))
-            self.writeline('</div>')
+            self.newline()
+    def write_include (self, name, lang="python") :
+        if os.path.exists(name) :
+            path = name
+        else :
+            path = os.path.join(os.path.dirname(self.inpath), name)
+        if not os.path.exists(path) :
+            err("include file %r not found" % name)
+        with open(path) as infile :
+            self.newline()
+            self.writeline("    :::%s" % lang)
+            for line in infile :
+                self.writeline("    " + line.rstrip())
+            self.newline()
 
 
 def main (finder, args) :
 def main (finder, args) :
     try :
     try :

+"""
+@todo: revise (actually make) documentation
+"""