PEP8 compliance and documentation update

git-svn-id: https://svn.osgeo.org/grass/grass/trunk@52670 15284696-431f-4ddb-bdfa-cd5b030d7da7

lib/python/temporal/abstract_dataset.py

@@ -310,18 +310,28 @@ class AbstractDataset(object):
         return statement
 
     def set_time_to_absolute(self):
+        """!Set the temporal type to absolute"""
         self.base.set_ttype("absolute")
 
     def set_time_to_relative(self):
+        """!Set the temporal type to relative"""
         self.base.set_ttype("relative")
 
     def is_time_absolute(self):
+        """!Return True in case the temporal type is absolute
+        
+        @return True if temporal type is absolute, False otherwise
+        """
         if "temporal_type" in self.base.D:
             return self.base.get_ttype() == "absolute"
         else:
             return None
 
     def is_time_relative(self):
+        """!Return True in case the temporal type is relative
+        
+        @return True if temporal type is relative, False otherwise
+        """
         if "temporal_type" in self.base.D:
             return self.base.get_ttype() == "relative"
         else:

lib/python/temporal/abstract_space_time_dataset.py

@@ -213,9 +213,10 @@ class AbstractSpaceTimeDataset(AbstractDataset):
            The map list must be ordered by start time
 
            The temporal type can be:
-           * point    -> only the start time is present
-           * interval -> start and end time
-           * invalid  -> No valid time point or interval found
+           
+           - point    -> only the start time is present
+           - interval -> start and end time
+           - invalid  -> No valid time point or interval found
 
            @param maps: A sorted (start_time) list of AbstractDataset objects
            @param dbif: The database interface to be used
@@ -318,23 +319,24 @@ class AbstractSpaceTimeDataset(AbstractDataset):
 
            Allowed and not allowed temporal relationships for correct topology:
            @verbatim
-           * after      -> allowed
-           * precedes   -> allowed
-           * follows    -> allowed
-           * precedes   -> allowed
-
-           * equivalent -> not allowed
-           * during     -> not allowed
-           * contains   -> not allowed
-           * overlaps   -> not allowed
-           * overlapped -> not allowed
-           * starts     -> not allowed
-           * finishes   -> not allowed
-           * started    -> not allowed
-           * finished   -> not allowed
+           - after      -> allowed
+           - precedes   -> allowed
+           - follows    -> allowed
+           - precedes   -> allowed
+
+           - equivalent -> not allowed
+           - during     -> not allowed
+           - contains   -> not allowed
+           - overlaps   -> not allowed
+           - overlapped -> not allowed
+           - starts     -> not allowed
+           - finishes   -> not allowed
+           - started    -> not allowed
+           - finished   -> not allowed
            @endverbatim
 
            @param maps: A sorted (start_time) list of AbstractDataset objects
+           @param dbif: The database interface to be used
            @return True if topology is correct
         """
         if maps is None:
@@ -419,7 +421,7 @@ class AbstractSpaceTimeDataset(AbstractDataset):
                   only the start time is used for sampling. In case of mixed 
                   of interval data the user can chose between:
                   
-                  * start: Select maps of which the start time is 
+                  - start: Select maps of which the start time is 
                     located in the selection granule
                     @verbatim
                     map    :        s
@@ -432,14 +434,14 @@ class AbstractSpaceTimeDataset(AbstractDataset):
                     granule:  s-----------------e
                     @endverbatim
 
-                  * during: Select maps which are temporal 
+                  - during: Select maps which are temporal 
                     during the selection granule
                     @verbatim
                     map    :     s-----------e
                     granule:  s-----------------e
                     @endverbatim
 
-                  * overlap: Select maps which temporal overlap 
+                  - overlap: Select maps which temporal overlap 
                     the selection granule
                     @verbatim
                     map    :     s-----------e
@@ -449,28 +451,28 @@ class AbstractSpaceTimeDataset(AbstractDataset):
                     granule:  s----------e
                     @endverbatim
 
-                  * contain: Select maps which temporally contain 
+                  - contain: Select maps which temporally contain 
                     the selection granule
                     @verbatim
                     map    :  s-----------------e
                     granule:     s-----------e
                     @endverbatim
 
-                  * equal: Select maps which temporally equal 
+                  - equal: Select maps which temporally equal 
                     to the selection granule
                     @verbatim
                     map    :  s-----------e
                     granule:  s-----------e
                     @endverbatim
 
-                  * follows: Select maps which temporally follow 
+                  - follows: Select maps which temporally follow 
                     the selection granule
                     @verbatim
                     map    :              s-----------e
                     granule:  s-----------e
                     @endverbatim
 
-                  * precedes: Select maps which temporally precedes 
+                  - precedes: Select maps which temporally precedes 
                     the selection granule
                     @verbatim
                     map    :  s-----------e
@@ -735,8 +737,8 @@ class AbstractSpaceTimeDataset(AbstractDataset):
            @param order: The SQL order statement to be used to order the 
                          objects in the list without "ORDER BY"
            @param dbif: The database interface to be used
-
-           In case nothing found None is returned
+           @return The ordered map object list, 
+                   In case nothing found None is returned
         """
 
         dbif, connect = init_dbif(dbif)

lib/python/temporal/base.py

@@ -279,7 +279,7 @@ class SQLDatabaseInterface(DictSQLSerializer):
             dbif.close()
 
     def get_is_in_db_statement(self):
-        """Return the selection string"""
+        """!Return the selection string"""
         return "SELECT id FROM " + self.get_table_name() + \
                " WHERE id = \'" + str(self.ident) + "\';\n"
 

lib/python/temporal/core.py

@@ -9,7 +9,7 @@ SQL database and to establish a connection to the database.
 
 Usage:
 
-\code
+@code
 
 >>> import grass.temporal as tgis
 >>> # Create the temporal database
@@ -25,7 +25,7 @@ Usage:
 "SELECT name from raster_base where name = 'precipitation'"
 >>> dbif.close()
 
-\endcode
+@endcode
 
 (C) 2008-2011 by the GRASS Development Team
 This program is free software under the GNU General Public
@@ -212,8 +212,8 @@ class SQLDatabaseInterfaceConnection():
     """!This class represents the database interface connection
 
        The following DBMS are supported:
-       * sqlite via the sqlite3 standard library
-       * postgresql via psycopg2
+         * sqlite via the sqlite3 standard library
+         * postgresql via psycopg2
 
     """
     def __init__(self):
@@ -250,6 +250,22 @@ class SQLDatabaseInterfaceConnection():
 
     def mogrify_sql_statement(self, content):
         """!Return the SQL statement and arguments as executable SQL string
+        
+           @param content: The content as tuple with two entries, the first 
+                           entry is the SQL statement with DBMI specific
+                           place holder (?), the second entry is the argument
+                           list that should substitue the place holder.
+            
+           Usage:
+           
+           @code
+           
+           >>> dbif = SQLDatabaseInterfaceConnection()
+           >>> dbif.mogrify_sql_statement(["SELECT ctime FROM raster_base WHERE id = ?",
+           ... ["soil@PERMANENT",]])
+           "SELECT ctime FROM raster_base WHERE id = 'soil@PERMANENT'"
+           
+           @endcode
         """
         sql = content[0]
         args = content[1]
@@ -350,13 +366,18 @@ def init_dbif(dbif):
         if not a new one will be created, connected and True will be returned
 
         Usage code sample:
-        \code
+        @code
+        
+        dbif, connect = tgis.init_dbif(None)
+        
+        sql = dbif.mogrify_sql_statement(["SELECT * FROM raster_base WHERE ? = ?"],
+                                               ["id", "soil@PERMANENT"])
+        dbif.execute_transaction(sql)
         
-        dbif, connect = tgis.init_dbif(dbif)
         if connect:
             dbif.close()
         
-        \code
+        @endcode
     """
     if dbif is None:
         dbif = SQLDatabaseInterfaceConnection()

lib/python/temporal/datetime_math.py

@@ -206,11 +206,11 @@ def increment_datetime(mydate, years=0, months=0, weeks=0, days=0, hours=0,
 def adjust_datetime_to_granularity(mydate, granularity):
     """!Modify the datetime object to fit the given granularity    
     
-        * Years will start at the first of Januar
-        * Months will start at the first day of the month
-        * Days will start at the first Hour of the day
-        * Hours will start at the first minute of an hour
-        * Minutes will start at the first second of a minute
+        - Years will start at the first of Januar
+        - Months will start at the first day of the month
+        - Days will start at the first Hour of the day
+        - Hours will start at the first minute of an hour
+        - Minutes will start at the first second of a minute
         
         Usage:
         

lib/python/temporal/metadata.py

@@ -509,15 +509,11 @@ class Raster3DMetadata(RasterMetadataBase):
 
 class VectorMetadata(SQLDatabaseInterface):
     """!This is the vector metadata class
-       
+        
         This class is the interface to the vector_metadata table in the
         temporal database that stores the metadata of all registered 
-        3D raster maps.
+        vector maps.
         
-        The metadata includes all raster metadata variables and additional
-        the number of depths, the top-bottom resolution and the space time 3D
-        raster dataset register table is stored.
-       
         Usage:
         
         @code
@@ -693,7 +689,8 @@ class VectorMetadata(SQLDatabaseInterface):
             return None
 
     def get_3d_info(self):
-        """!Return True if the map is three dimensional, False if not and None if not info was found"""
+        """!Return True if the map is three dimensional, 
+           False if not and None if not info was found"""
         if "is_3d" in self.D:
             return self.D["is_3d"]
         else:
@@ -976,11 +973,12 @@ class STDSMetadataBase(SQLDatabaseInterface):
 
 class STDSRasterMetadataBase(STDSMetadataBase):
     """!This is the space time dataset metadata base 
-       class for strds and str3ds datasets
+        class for strds and str3ds datasets
 
-       Most of the metadata values are set by triggers in the database when
-       new raster or voxel maps are added. Therefor only some 
-       set- an many get-functions are available.
+        Most of the metadata values are set by SQL scripts in the database when
+        new maps are added. Therefor only some set- an many 
+        get-functions are available.
+        
        
         Usage:
         
@@ -1168,6 +1166,10 @@ class STRDSMetadata(STDSRasterMetadataBase):
         temporal database that stores the metadata of all registered 
         space time raster datasets
         
+        Most of the metadata values are set by SQL scripts in the database when
+        new raster maps are added. Therefor only some set- an many 
+        get-functions are available.
+        
         Usage:
         
         @code
@@ -1259,12 +1261,16 @@ class STRDSMetadata(STDSRasterMetadataBase):
 
 
 class STR3DSMetadata(STDSRasterMetadataBase):
-    """!This is the space time raster3d metadata class
+    """!This is the space time 3D raster metadata class
     
         This class is the interface to the str3ds_metadata table in the
         temporal database that stores the metadata of all registered 
         space time 3D raster datasets
         
+        Most of the metadata values are set by SQL scripts in the database when
+        new 3D raster maps are added. Therefor only some set- an many 
+        get-functions are available.
+        
         Usage:
         
         @code
@@ -1391,8 +1397,12 @@ class STR3DSMetadata(STDSRasterMetadataBase):
 
 class STVDSMetadata(STDSMetadataBase):
     """!This is the space time vector dataset metadata class
-    
-       Most of the metadata values are set by triggers in the database when
+        
+       This class is the interface to the stvds_metadata table in the
+       temporal database that stores the metadata of all registered 
+       space time vector datasets
+        
+       Most of the metadata values are set by SQL scripts in the database when
        new vector maps are added. Therefor only some set- an many get-functions
        are available.
         

lib/python/temporal/pythontemporallib.dox

@@ -8,20 +8,57 @@ TODO: add some documentation
 
 List of modules:
 
+Core functionality such as the database interface connection to sqlite3 
+and postgresql as well as the creation of the temporal database are defined here:
+
+- python::temporal::core
+
+In these modules are the temporal database interfaces for raster maps, 
+3D raster maps, vector maps and space time datasets defined. 
+
+Additionally the temporal and spatial extent modules implement the topological 
+relationship computation that is needed for spatio-temporal topology computation.
+
+- python::temporal::base
+- python::temporal::spatial_extent
+- python::temporal::temporal_extent
+- python::temporal::metadata
+
+Several "abstract" modules are defined that implement the shared functionality 
+of time stamped maps and space time datasets, such as temporal and spatial
+handling and representation. 
+
 - python::temporal::abstract_dataset
 - python::temporal::abstract_map_dataset
 - python::temporal::abstract_space_time_dataset
-- python::temporal::aggregation
-- python::temporal::base
-- python::temporal::core
-- python::temporal::datetime_math
-- python::temporal::metadata
+
+All dataset classes that are used in the GRASS temporal modules are specified
+here:
+
 - python::temporal::space_time_datasets
-- python::temporal::space_time_datasets_tools
-- python::temporal::spatial_extent
-- python::temporal::temporal_extent
-- python::temporal::temporal_granularity
+
+Helper functions to compute temporal granularity, handling of datetime objects
+and their conversion as well as topology computation are defined in these modules:
+
+- python::temporal::datetime_math
 - python::temporal::temporal_relationships
+- python::temporal::temporal_granularity
+
+Functionality that is shared between different temporal GRASS modules, such as
+map listing, map registration and unregistration, aggregation, extraction,
+map calculation, statistics as well as import and export of 
+space time datasets are defined here:
+
+- python::temporal::space_time_datasets_tools
+- python::temporal::aggregation
+- python::temporal::extract
+- python::temporal::mapcalc
+- python::temporal::stds_export
+- python::temporal::stds_import
+- python::temporal::univar_statistics
+
+Lots of unit tests:
+
 - python::temporal::unit_tests
 
 \section pythonTempAuthors Authors

lib/python/temporal/space_time_datasets.py

@@ -811,7 +811,8 @@ class SpaceTimeRasterDataset(AbstractSpaceTimeDataset):
         return SpaceTimeRasterDataset(ident)
 
     def get_new_map_instance(self, ident):
-        """!Return a new instance of a map dataset which is associated with the type of this class"""
+        """!Return a new instance of a map dataset which is associated "
+        "with the type of this class"""
         return RasterDataset(ident)
 
     def get_map_register(self):

lib/python/temporal/spatial_extent.py

@@ -94,15 +94,29 @@ class SpatialExtent(SQLDatabaseInterface):
         self.set_projection(proj)
 
     def overlapping_2d(self, extent):
-        """!Return True if the two dimensional extents overlap. 
-           Code is lend from wind_overlap.c in lib/gis
-
-           Overlapping includes the spatial relations:
-           * contain
-           * in
-           * cover
-           * covered
-           * equivalent
+        """!Return True if this (A) and the provided spatial extent (B) overlaps
+        in two dimensional space. 
+        Code is lend from wind_overlap.c in lib/gis
+        
+        Overlapping includes the spatial relations:
+        
+        - contain
+        - in
+        - cover
+        - covered
+        - equivalent
+        
+         @code
+         
+         >>> A = SpatialExtent(north=80, south=20, east=60, west=10)
+         >>> B = SpatialExtent(north=80, south=20, east=60, west=10)
+         >>> A.overlapping_2d(B)
+         True
+         
+         @endcode
+        
+        @param extent: The spatial extent to check overlapping with
+        @return True or False
         """
 
         if self.get_projection() != extent.get_projection():
@@ -140,25 +154,30 @@ class SpatialExtent(SQLDatabaseInterface):
         return True
 
     def overlapping(self, extent):
-        """!Return True if the three dimensional extents overlap
-
-       Overlapping includes the spatial relations:
-       * contain
-       * in
-       * cover
-       * covered
-       * equivalent
-           
-        Usage:
+        """!Return True if this (A) and the provided spatial 
+        extent (B) overlaps in three dimensional space.
         
-        @code
+        Overlapping includes the spatial relations:
         
-        >>> A = SpatialExtent(north=80, south=20, east=60, west=10, bottom=-50, top=50)
-        >>> B = SpatialExtent(north=80, south=20, east=60, west=10, bottom=-50, top=50)
-        >>> A.overlapping(B)
-        True
-        
-        @endcode
+        - contain
+        - in
+        - cover
+        - covered
+        - equivalent
+            
+         Usage:
+         
+         @code
+         
+         >>> A = SpatialExtent(north=80, south=20, east=60, west=10, bottom=-50, top=50)
+         >>> B = SpatialExtent(north=80, south=20, east=60, west=10, bottom=-50, top=50)
+         >>> A.overlapping(B)
+         True
+         
+         @endcode
+         
+         @param extent: The spatial extent to check overlapping with
+         @return True or False
         """
 
         if not self.overlapping_2d(extent):
@@ -177,7 +196,10 @@ class SpatialExtent(SQLDatabaseInterface):
 
     def intersect_2d(self, extent):
         """!Return the two dimensional intersection as spatial_extent 
-           object or None in case no intersection was found.
+        object or None in case no intersection was found.
+       
+        @param extent: The spatial extent to intersect with
+         @return The intersection spatial extent
         """
 
         if not self.overlapping_2d(extent):
@@ -230,8 +252,10 @@ class SpatialExtent(SQLDatabaseInterface):
         
         @code
         
-        >>> A = SpatialExtent(north=80, south=20, east=60, west=10, bottom=-50, top=50)
-        >>> B = SpatialExtent(north=80, south=20, east=60, west=10, bottom=-50, top=50)
+        >>> A = SpatialExtent(north=80, south=20, east=60, west=10, 
+        ... bottom=-50, top=50)
+        >>> B = SpatialExtent(north=80, south=20, east=60, west=10, 
+        ... bottom=-50, top=50)
         >>> C = A.intersect(B)
         >>> C.print_info()
          +-------------------- Spatial extent ----------------------------------------+
@@ -241,7 +265,8 @@ class SpatialExtent(SQLDatabaseInterface):
          | West:....................... 10.0
          | Top:........................ 50.0
          | Bottom:..................... -50.0
-        >>> B = SpatialExtent(north=40, south=30, east=60, west=10, bottom=-50, top=50)
+        >>> B = SpatialExtent(north=40, south=30, east=60, west=10, 
+        ... bottom=-50, top=50)
         >>> C = A.intersect(B)
         >>> C.print_info()
          +-------------------- Spatial extent ----------------------------------------+
@@ -251,7 +276,8 @@ class SpatialExtent(SQLDatabaseInterface):
          | West:....................... 10.0
          | Top:........................ 50.0
          | Bottom:..................... -50.0
-        >>> B = SpatialExtent(north=40, south=30, east=60, west=30, bottom=-50, top=50)
+        >>> B = SpatialExtent(north=40, south=30, east=60, west=30, 
+        ... bottom=-50, top=50)
         >>> C = A.intersect(B)
         >>> C.print_info()
          +-------------------- Spatial extent ----------------------------------------+
@@ -261,7 +287,8 @@ class SpatialExtent(SQLDatabaseInterface):
          | West:....................... 30.0
          | Top:........................ 50.0
          | Bottom:..................... -50.0
-        >>> B = SpatialExtent(north=40, south=30, east=60, west=30, bottom=-30, top=50)
+        >>> B = SpatialExtent(north=40, south=30, east=60, west=30, 
+        ... bottom=-30, top=50)
         >>> C = A.intersect(B)
         >>> C.print_info()
          +-------------------- Spatial extent ----------------------------------------+
@@ -271,7 +298,8 @@ class SpatialExtent(SQLDatabaseInterface):
          | West:....................... 30.0
          | Top:........................ 50.0
          | Bottom:..................... -30.0
-        >>> B = SpatialExtent(north=40, south=30, east=60, west=30, bottom=-30, top=30)
+        >>> B = SpatialExtent(north=40, south=30, east=60, west=30, 
+        ... bottom=-30, top=30)
         >>> C = A.intersect(B)
         >>> C.print_info()
          +-------------------- Spatial extent ----------------------------------------+
@@ -283,6 +311,10 @@ class SpatialExtent(SQLDatabaseInterface):
          | Bottom:..................... -30.0
          
          @endcode
+         
+         
+         @param extent: The spatial extent to intersect with
+         @return The intersection spatial extent
         """
 
         if not self.overlapping(extent):
@@ -310,7 +342,8 @@ class SpatialExtent(SQLDatabaseInterface):
         return new
 
     def is_in_2d(self, extent):
-        """!Check two dimensional if the self is located in extent
+        """!Return True if this extent (A) is located in the provided spatial
+        extent (B) in two dimensions.
         
         @verbatim
          _____
@@ -319,6 +352,9 @@ class SpatialExtent(SQLDatabaseInterface):
         |_____|B 
         
         @endverbatim
+        
+        @param extent: The spatial extent
+        @return True or False
         """
         if self.get_projection() != extent.get_projection():
             core.error(_("Projections are different. Unable to compute "
@@ -357,20 +393,26 @@ class SpatialExtent(SQLDatabaseInterface):
         return True
 
     def is_in(self, extent):
-        """!Check three dimensional if the self is located in extent 
+        """!Return True if this extent (A) is located in the provided spatial
+        extent (B) in three dimensions.
         
         Usage:
         
         @code
         
-        >>> A = SpatialExtent(north=79, south=21, east=59, west=11, bottom=-49, top=49)
-        >>> B = SpatialExtent(north=80, south=20, east=60, west=10, bottom=-50, top=50)
+        >>> A = SpatialExtent(north=79, south=21, east=59, west=11, 
+        ... bottom=-49, top=49)
+        >>> B = SpatialExtent(north=80, south=20, east=60, west=10, 
+        ... bottom=-50, top=50)
         >>> A.is_in(B)
         True
         >>> B.is_in(A)
         False
         
         @endcode
+        
+        @param extent: The spatial extent
+        @return True or False
         """
         if not self.is_in_2d(extent):
             return False
@@ -389,16 +431,71 @@ class SpatialExtent(SQLDatabaseInterface):
         return True
 
     def contain_2d(self, extent):
-        """!Check two dimensional if self contains extent """
+        """!Return True if this extent (A) contains the provided spatial
+        extent (B) in two dimensions.
+        
+        Usage:
+        
+        @code
+        
+        >>> A = SpatialExtent(north=80, south=20, east=60, west=10)
+        >>> B = SpatialExtent(north=79, south=21, east=59, west=11)
+        >>> A.contain_2d(B)
+        True
+        >>> B.contain_2d(A)
+        False
+        
+        @endcode
+        
+        @param extent: The spatial extent
+        @return True or False
+        """
         return extent.is_in_2d(self)
 
-    def contain(self, extent):
-        """!Check three dimensional if self contains extent """
+    def contain(self, extent):        
+        """!Return True if this extent (A) contains the provided spatial
+        extent (B) in three dimensions.
+        
+        Usage:
+        
+        @code
+        
+        >>> A = SpatialExtent(north=80, south=20, east=60, west=10, 
+        ... bottom=-50, top=50)
+        >>> B = SpatialExtent(north=79, south=21, east=59, west=11, 
+        ... bottom=-49, top=49)
+        >>> A.contain(B)
+        True
+        >>> B.contain(A)
+        False
+        
+        @endcode
+        
+        @param extent: The spatial extent
+        @return True or False
+        """
         return extent.is_in(self)
 
     def equivalent_2d(self, extent):
-        """!Check two dimensional if self is equivalent to extent """
-
+        """!Return True if this extent (A) is equal to the provided spatial
+        extent (B) in two dimensions.
+        
+        Usage:
+        
+        @code
+        
+        >>> A = SpatialExtent(north=80, south=20, east=60, west=10)
+        >>> B = SpatialExtent(north=80, south=20, east=60, west=10)
+        >>> A.equivalent_2d(B)
+        True
+        >>> B.equivalent_2d(A)
+        True
+        
+        @endcode
+        
+        @param extent: The spatial extent
+        @return True or False
+        """
         if self.get_projection() != extent.get_projection():
             core.error(_("Projections are different. Unable to compute "
                          "equivalent_2d for spatial extents"))
@@ -436,7 +533,27 @@ class SpatialExtent(SQLDatabaseInterface):
         return True
 
     def equivalent(self, extent):
-        """!Check three dimensional if self is equivalent to extent """
+        """!Return True if this extent (A) is equal to the provided spatial
+        extent (B) in three dimensions.
+        
+        Usage:
+        
+        @code
+        
+        >>> A = SpatialExtent(north=80, south=20, east=60, west=10, 
+        ... bottom=-50, top=50)
+        >>> B = SpatialExtent(north=80, south=20, east=60, west=10, 
+        ... bottom=-50, top=50)
+        >>> A.equivalent(B)
+        True
+        >>> B.equivalent(A)
+        True
+        
+        @endcode
+        
+        @param extent: The spatial extent
+        @return True or False
+        """
 
         if not self.equivalent_2d(extent):
             return False
@@ -455,30 +572,35 @@ class SpatialExtent(SQLDatabaseInterface):
         return True
 
     def cover_2d(self, extent):
-        """!Return True if two dimensional self covers extent
+        """!Return True if this extent (A) covers the provided spatial
+        extent (B) in two dimensions.
            
-           @verbatim
-            _____    _____    _____    _____
-           |A  __|  |__  A|  |A | B|  |B | A|
-           |  |B |  | B|  |  |  |__|  |__|  |
-           |__|__|  |__|__|  |_____|  |_____|
-
-            _____    _____    _____    _____
-           |A|B| |  |A  __|  |A _  |  |__  A|
-           | |_| |  |  |__|B | |B| | B|__|  |
-           |_____|  |_____|  |_|_|_|  |_____|
-
-            _____    _____    _____    _____
-           |A|B  |  |_____|A |A|B|A|  |_____|A
-           | |   |  |B    |  | | | |  |_____|B
-           |_|___|  |_____|  |_|_|_|  |_____|A
-           
-           @endverbatim
+        @verbatim
+         _____    _____    _____    _____
+        |A  __|  |__  A|  |A | B|  |B | A|
+        |  |B |  | B|  |  |  |__|  |__|  |
+        |__|__|  |__|__|  |_____|  |_____|
+        
+         _____    _____    _____    _____
+        |A|B| |  |A  __|  |A _  |  |__  A|
+        | |_| |  |  |__|B | |B| | B|__|  |
+        |_____|  |_____|  |_|_|_|  |_____|
+        
+         _____    _____    _____    _____
+        |A|B  |  |_____|A |A|B|A|  |_____|A
+        | |   |  |B    |  | | | |  |_____|B
+        |_|___|  |_____|  |_|_|_|  |_____|A
+        
+        @endverbatim
+        
+        The following cases are excluded:
+        
+        - contain
+        - in
+        - equivalent
 
-           The following cases are excluded:
-           * contain
-           * in
-           * equivalent
+        @param extent: The spatial extent
+        @return True or False
         """
 
         if self.get_projection() != extent.get_projection():
@@ -540,16 +662,21 @@ class SpatialExtent(SQLDatabaseInterface):
         return True
 
     def cover(self, extent):
-        """!Return True if three dimensional self covers extent
+        """!Return True if this extent covers the provided spatial
+        extent in three dimensions.
+        
+        The following cases are excluded:
+        
+        - contain
+        - in
+        - equivalent
 
-           The following cases are excluded:
-           * contain
-           * in
-           * equivalent
+        @param extent: The spatial extent
+        @return True or False
         """
-
         if self.get_projection() != extent.get_projection():
-            core.error(_("Projections are different. Unable to compute cover for spatial extents"))
+            core.error(_("Projections are different. Unable to compute "
+                         "cover for spatial extents"))
             return False
 
         # Exclude equivalent_2d
@@ -625,34 +752,61 @@ class SpatialExtent(SQLDatabaseInterface):
         return True
 
     def covered_2d(self, extent):
-        """!Check two dimensional if self is covered by  extent """
+        """!Return True if this extent is covered by the provided spatial
+        extent in two dimensions.
+        
+        The following cases are excluded:
+        
+        - contain
+        - in
+        - equivalent
+
+        @param extent: The spatial extent
+        @return True or False
+        """
 
         return extent.cover_2d(self)
 
     def covered(self, extent):
-        """!Check three dimensional if self is covered by extent """
+        """!Return True if this extent is covered by the provided spatial
+        extent in three dimensions.
+        
+        The following cases are excluded:
+        
+        - contain
+        - in
+        - equivalent
+
+        @param extent: The spatial extent
+        @return True or False
+        """
 
         return extent.cover(self)
 
     def overlap_2d(self, extent):
-        """!Return True if the two dimensional extents overlap. Code is 
-           lend from wind_overlap.c in lib/gis
+        """!Return True if this extent (A) overlaps with the provided spatial
+        extent (B) in two dimensions.
+        Code is lend from wind_overlap.c in lib/gis
+        
+        @verbatim
+         _____
+        |A  __|__
+        |  |  | B|
+        |__|__|  |
+           |_____|
            
-           @verbatim
-            _____
-           |A  __|__
-           |  |  | B|
-           |__|__|  |
-              |_____|
-              
-           @endverbatim
-
-           The following cases are excluded:
-           * contain
-           * in
-           * cover
-           * covered
-           * equivalent
+        @endverbatim
+        
+        The following cases are excluded:
+        
+        - contain
+        - in
+        - cover
+        - covered
+        - equivalent
+           
+        @param extent: The spatial extent
+        @return True or False
         """
 
         if self.contain_2d(extent):
@@ -700,14 +854,19 @@ class SpatialExtent(SQLDatabaseInterface):
         return True
 
     def overlap(self, extent):
-        """!Return True if the three dimensional extents overlap
-
-           The following cases are excluded:
-           * contain
-           * in
-           * cover
-           * covered
-           * equivalent
+        """!Return True if this extent overlaps with the provided spatial
+        extent in three dimensions.
+
+        The following cases are excluded:
+        
+        - contain
+        - in
+        - cover
+        - covered
+        - equivalent
+           
+        @param extent: The spatial extent
+        @return True or False
         """
 
         if self.is_in(extent):
@@ -763,27 +922,37 @@ class SpatialExtent(SQLDatabaseInterface):
         return True
 
     def meet_2d(self, extent):
-        """!Check if self and extent meet each other in two dimensions
+        """!Return True if this extent (A) meets with the provided spatial
+        extent (B) in two dimensions.
         
         @verbatim
-          _____ _____    _____ _____
-         |  A  |  B  |  |  B  |  A  |
-         |_____|     |  |     |     |
-               |_____|  |_____|_____|
-
+          _____ _____ 
+         |  A  |  B  |
+         |_____|     |
+               |_____|
+          _____ _____
+         |  B  |  A  |
+         |     |     |
+         |_____|_____|
            ___
           | A |
           |   |
-          |___|    _____
-         |  B  |  |  B  |
-         |     |  |     |
-         |_____|  |_____|_
-                    |  A  |
-                    |     |
-                    |_____|
-         
+          |___| 
+         |  B  |
+         |     |  
+         |_____|  
+          _____
+         |  B  |
+         |     |
+         |_____|_
+           |  A  |
+           |     |
+           |_____|
+             
          @endverbatim
-
+           
+        @param extent: The spatial extent
+        @return True or False
         """
 
         eN = extent.get_north()
@@ -841,7 +1010,12 @@ class SpatialExtent(SQLDatabaseInterface):
         return True
 
     def meet(self, extent):
-        """!Check if self and extent meet each other in three dimensions"""
+        """!Return True if this extent meets with the provided spatial
+        extent in three dimensions.
+           
+        @param extent: The spatial extent
+        @return True or False
+        """
         eN = extent.get_north()
         eS = extent.get_south()
         eE = extent.get_east()
@@ -916,7 +1090,21 @@ class SpatialExtent(SQLDatabaseInterface):
         return True
 
     def disjoint_2d(self, extent):
-        """!Return True if the two dimensional extents are disjoint
+        """!Return True if this extent (A) is disjoint with the provided spatial
+        extent (B) in three dimensions.
+        
+        @verbatim
+          _____ 
+         |  A  |
+         |_____|       
+         _______ 
+        |   B   |
+        |_______|
+                     
+         @endverbatim
+         
+        @param extent: The spatial extent
+        @return True or False
         """
 
         if self.overlapping_2d(extent) or self.meet_2d(extent):
@@ -924,7 +1112,11 @@ class SpatialExtent(SQLDatabaseInterface):
         return True
 
     def disjoint(self, extent):
-        """!Return True if the three dimensional extents are disjoint
+        """!Return True if this extent is disjoint with the provided spatial
+        extent in three dimensions.
+           
+        @param extent: The spatial extent
+        @return True or False
         """
 
         if self.overlapping(extent) or self.meet(extent):
@@ -932,17 +1124,19 @@ class SpatialExtent(SQLDatabaseInterface):
         return True
 
     def spatial_relation_2d(self, extent):
-        """!Returns the two dimensional spatial relation between self and extent
+        """!Returns the two dimensional spatial relation between this
+        extent and the provided spatial extent in two dimensions.
 
         Spatial relations are:
-        * disjoint
-        * meet
-        * overlap
-        * cover
-        * covered
-        * in
-        * contain
-        * equivalent
+        
+        - disjoint
+        - meet
+        - overlap
+        - cover
+        - covered
+        - in
+        - contain
+        - equivalent
         
         Usage: see self.spatial_relation()
         """
@@ -967,17 +1161,19 @@ class SpatialExtent(SQLDatabaseInterface):
         return "unknown"
 
     def spatial_relation(self, extent):
-        """!Returns the three dimensional spatial relation between self and extent
+        """!Returns the two dimensional spatial relation between this
+        extent and the provided spatial extent in three dimensions.
 
         Spatial relations are:
-        * disjoint
-        * meet
-        * overlap
-        * cover
-        * covered
-        * in
-        * contain
-        * equivalent
+        
+        - disjoint
+        - meet
+        - overlap
+        - cover
+        - covered
+        - in
+        - contain
+        - equivalent
             
         
         Usage:
@@ -1157,7 +1353,7 @@ class SpatialExtent(SQLDatabaseInterface):
         return "unknown"
 
     def set_spatial_extent(self, north, south, east, west, top, bottom):
-        """!Set the spatial extent"""
+        """!Set the three dimensional spatial extent"""
 
         self.set_north(north)
         self.set_south(south)
@@ -1176,6 +1372,7 @@ class SpatialExtent(SQLDatabaseInterface):
             self.D["proj"] = proj
 
     def set_spatial_extent_2d(self, north, south, east, west):
+        """!Set the two dimensional spatial extent"""
 
         self.set_north(north)
         self.set_south(south)

lib/python/temporal/temporal_extent.py

@@ -577,19 +577,20 @@ class AbstractTemporalExtent(SQLDatabaseInterface):
            [Allen and Ferguson 1994 Actions and Events in Interval Temporal Logic]
            
            The following temporal relationships are supported:
-           * equivalent
-           * during
-           * contains
-           * overlaps
-           * overlapped
-           * after
-           * before
-           * starts
-           * finishes
-           * started
-           * finished
-           * follows
-           * precedes
+           
+               - equivalent
+               - during
+               - contains
+               - overlaps
+               - overlapped
+               - after
+               - before
+               - starts
+               - finishes
+               - started
+               - finished
+               - follows
+               - precedes
            
            @param extent: The temporal extent 
            @return The name of the temporal relation or None if no relation found
@@ -886,7 +887,7 @@ class STVDSAbsoluteTime(STDSAbsoluteTime):
 ###############################################################################
 
 class RelativeTemporalExtent(AbstractTemporalExtent):
-    """!This is the relative time class for all maps and spacetime datasets
+    """!This is the relative time class for all maps and space time datasets
 
         start_time and end_time must be of type integer
        
@@ -894,7 +895,7 @@ class RelativeTemporalExtent(AbstractTemporalExtent):
         
         @code
        
-        >>> A = RelativeTemporalExtent(table="raster_absolute_time",
+        >>> A = RelativeTemporalExtent(table="raster_relative_time",
         ... ident="soil@PERMANENT", start_time=0, end_time=1, unit="years")
         >>> A.id
         'soil@PERMANENT'
@@ -925,12 +926,13 @@ class RelativeTemporalExtent(AbstractTemporalExtent):
 
     def set_unit(self, unit):
         """!Set the unit of the relative time. Valid units are:
-           * years
-           * months
-           * days
-           * hours
-           * minutes
-           * seconds
+        
+           - years
+           - months
+           - days
+           - hours
+           - minutes
+           - seconds
         """
         self.D["unit"] = unit
 
@@ -997,7 +999,7 @@ class VectorRelativeTime(RelativeTemporalExtent):
 ###############################################################################
 
 class STDSRelativeTime(RelativeTemporalExtent):
-    """!This is the relative time class for all maps and spacetime datasets
+    """!This is the relative time class for all maps and space time datasets
 
         start_time and end_time must be of type integer
        
@@ -1005,11 +1007,11 @@ class STDSRelativeTime(RelativeTemporalExtent):
         
         @code
        
-        >>> A = STDSRelativeTime(table="raster_absolute_time",
-        ... ident="soil@PERMANENT", start_time=0, end_time=1, unit="years",
+        >>> A = STDSRelativeTime(table="strds_relative_time",
+        ... ident="strds@PERMANENT", start_time=0, end_time=1, unit="years",
         ... granularity=5, map_time="interval")
         >>> A.id
-        'soil@PERMANENT'
+        'strds@PERMANENT'
         >>> A.start_time
         0
         >>> A.end_time