--- a/python/moving.py	Sun Jan 27 00:51:48 2013 -0500
+++ b/python/moving.py	Tue Jan 29 10:36:17 2013 -0500
@@ -11,9 +11,8 @@
 __metaclass__ = type
 
 class Interval:
-    '''Generic Interval'''
+    '''Generic interval: a subset of real numbers (not iterable)'''
     def __init__(self, first=0, last=-1, revert = False):
-        'Warning, do not revert if last<first, it contradicts the definition of empty'
         if revert and last<first:
             self.first=last
             self.last=first
@@ -44,7 +43,7 @@
         return (self.first<=instant and self.last>=instant)
 
     def inside(self, interval2):
-        'indicates if the temporal interval of self is comprised in interval2'
+        '''Indicates if the temporal interval of self is comprised in interval2'''
         return (self.first >= interval2.first) and (self.last <= interval2.last)
 
     def union(self, interval2):
@@ -75,8 +74,10 @@
 
 
 class TimeInterval(Interval):
-    '''Temporal interval based on frame numbers (hence the modified length method)
-    may be modified directly by setting first and last'''
+    '''Temporal interval: set of instants at fixed time step, between first and last, included
+    
+    For example: based on frame numbers (hence the modified length method)
+    It may be modified directly by setting first and last'''
 
     def __init__(self, first=0, last=-1):
         Interval.__init__(self, first, last, False)
@@ -107,10 +108,10 @@
 # We will use the polygon class of Shapely
 
 class STObject:
-    '''Class for spatio-temporal object
-    i.e. with temporal and spatial existence 
+    '''Class for spatio-temporal object, i.e. with temporal and spatial existence 
     (time interval and bounding polygon for positions (e.g. rectangle)).
-    It does not mean that the object is defined 
+
+    It may not mean that the object is defined 
     for all time instants within the time interval'''
 
     def __init__(self, num = None, timeInterval = None, boundingPolygon = None):
@@ -168,7 +169,7 @@
         return self.x*self.x+self.y*self.y
 
     def norm2(self):
-        '2-norm distance (Euclidean distance)'
+        '''2-norm distance (Euclidean distance)'''
         return sqrt(self.norm2Squared())
 
     def norm1(self):
@@ -235,7 +236,7 @@
         scatter([p.x for p in points],[p.y for p in points], c=color)
 
 class NormAngle:
-    'alternate encoding of a point, by its norm and orientation'
+    '''Alternate encoding of a point, by its norm and orientation'''
 
     def __init__(self, norm, angle):
         self.norm = norm
@@ -328,10 +329,9 @@
 # TODO: implement a better algorithm for intersections of sets of segments http://en.wikipedia.org/wiki/Line_segment_intersection
 
 class Trajectory:
-    '''Class for trajectories
-    i.e. a temporal sequence of positions
+    '''Class for trajectories: temporal sequence of positions
 
-    the class is iterable.'''
+    The class is iterable'''
 
     def __init__(self, positions=None):
         if positions != None:
@@ -526,9 +526,8 @@
 userType2Num = utils.inverseEnumeration(userTypeNames)
 
 class MovingObject(STObject):
-    '''Class for moving objects
-    i.e. with a trajectory and a geometry (volume) (constant)
-    and a usertype (e.g. road user)
+    '''Class for moving objects: a spatio-temporal object 
+    with a trajectory and a geometry (constant volume over time) and a usertype (e.g. road user)
     '''
 
     def __init__(self, num = None, timeInterval = None, positions = None, geometry = None, userType = None):
@@ -637,4 +636,3 @@
     unittest.TextTestRunner().run(suite)
     #doctest.testmod()
     #doctest.testfile("example.txt")
-