pygrass doc: improve documentation on vector and raster classes

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

lib/python/pygrass/docs/raster.rst

@@ -1,7 +1,7 @@
 .. _raster-label:
 
-Raster
-======
+Introduction on Raster
+===========================
 
 PyGRASS uses 4 different Raster classes, that respect the 4 different approaches
 of GRASS-C API.

lib/python/pygrass/docs/vector.rst

@@ -1,6 +1,6 @@
 
-Vector
-========
+Introduction on Vector
+=========================
 
 Instantiation and basic interaction. ::
 
@@ -114,16 +114,17 @@ Now, find an area with an island inside... ::
     Bbox(199947.296494, 199280.969494, 754920.623987, 754351.812986)
 
 
-VectorTopo
+
+Vector
 ----------
 
-.. autoclass:: pygrass.vector.VectorTopo
+.. autoclass:: pygrass.vector.Vector
     :members:
 
-Vector
+VectorTopo
 ----------
 
-.. autoclass:: pygrass.vector.Vector
+.. autoclass:: pygrass.vector.VectorTopo
     :members:
 
 
@@ -165,7 +166,7 @@ Isles
 Area
 --------
 
-.. autoclass:: pygrass.vector.geometry.Boundary
+.. autoclass:: pygrass.vector.geometry.Area
     :members:
 
 Utils

lib/python/pygrass/raster/history.py

@@ -10,31 +10,29 @@ import datetime
 
 
 class History(object):
-    """
-    *Examples*
-
-    ::
-        >>> import grass.lib.gis as libgis
-        >>> libgis.G_gisinit('')
-        >>> hist = History('elevation')
-        >>> hist.creator
-        'helena'
-        >>> hist.src1
-        ''
-        >>> hist.src2
-        ''
-        >>> hist.keyword
-        'generated by r.proj'
-        >>> hist.date
-        datetime.datetime(2006, 11, 7, 1, 9, 51)
-        >>> hist.mapset
-        'PERMANENT'
-        >>> hist.maptype
-        'raster'
-        >>> hist.title
-        'elev_ned10m'
-
-    ..
+    """History class help to manage all the metadata of a raster map
+
+    >>> import grass.lib.gis as libgis
+    >>> libgis.G_gisinit('')
+    >>> hist = History('elevation')
+    >>> hist.read()
+    >>> hist.creator
+    'helena'
+    >>> hist.src1
+    ''
+    >>> hist.src2
+    ''
+    >>> hist.keyword
+    'generated by r.proj'
+    >>> hist.date
+    datetime.datetime(2006, 11, 7, 1, 9, 51)
+    >>> hist.mapset
+    'PERMANENT'
+    >>> hist.maptype
+    'raster'
+    >>> hist.title
+    'elev_ned10m'
+
     """
     def __init__(self, name, mapset='', mtype='',
                  creator='', src1='', src2='', keyword='',
@@ -208,7 +206,7 @@ class History(object):
                                              *args)
 
     def clear(self):
-        """Rast_clear_history"""
+        """Clear the history"""
         libraster.Rast_clear_history(self.c_hist)
 
     def command(self):
@@ -232,7 +230,8 @@ class History(object):
                                            ctypes.c_int(line))
 
     def read(self):
-        """Rast_read_history. ::
+        """Read the history of map, users need to use this function to
+        obtain all the information of map. ::
 
             >>> import grass.lib.gis as libgis
             >>> libgis.G_gisinit('')

lib/python/pygrass/vector/__init__.py

@@ -40,7 +40,7 @@ _NUMOF = {"areas": libvect.Vect_get_num_areas,
 #=============================================
 
 class Vector(Info):
-    """ ::
+    """Vector class is the grass vector format without topology
 
         >>> from grass.pygrass.vector import Vector
         >>> cens = Vector('census')
@@ -55,7 +55,6 @@ class Vector(Info):
         >>> cens.overwrite
         False
 
-    ..
     """
     def __init__(self, name, mapset='', *args, **kwargs):
         # Set map name and mapset
@@ -103,6 +102,7 @@ class Vector(Info):
 
     @must_be_open
     def rewind(self):
+        """Rewind vector map to cause reads to start at beginning."""
         if libvect.Vect_rewind(self.c_mapinfo) == -1:
             raise GrassError("Vect_rewind raise an error.")
 
@@ -110,21 +110,17 @@ class Vector(Info):
     def write(self, geo_obj, attrs=None, set_cats=True):
         """Write geometry features and attributes.
 
-        Parameters
-        ----------
-
-        geo_obj : geometry GRASS object
-            A geometry grass object define in grass.pygrass.vector.geometry.
-        attrs: list, optional
-            A list with the values that will be insert in the attribute table.
-        set_cats, bool, optional
-            If True, the category of the geometry feature is set using the
-            default layer of the vector map and a progressive category value
-            (default), otherwise the c_cats attribute of the geometry object
-            will be used.
-
-        Examples
-        --------
+        :param geo_obj: a geometry grass object define in
+                        grass.pygrass.vector.geometry
+        :type geo_obj: geometry GRASS object        
+        :param attrs: a list with the values that will be insert in the
+                      attribute table.
+        :type attrs: list
+        :param set_cats: if True, the category of the geometry feature is set
+                         using the default layer of the vector map and a
+                         progressive category value (default), otherwise the
+                         c_cats attribute of the geometry object will be used.
+        :type set_cats: bool
 
         Open a new vector map ::
 
@@ -175,7 +171,6 @@ class Vector(Info):
             >>> new.close()
             >>> new.remove()
 
-        ..
         """
         self.n_lines += 1
         if self.table is not None and attrs:
@@ -208,8 +203,6 @@ class Vector(Info):
         """Return if vector has color table associated in file system;
         Color table stored in the vector's attribute table well be not checked
 
-        Examples
-        --------
         >>> cens = Vector('census')
         >>> cens.open()
         >>> cens.has_color_table()
@@ -252,6 +245,7 @@ class VectorTopo(Vector):
         >>> schools.is_open()
         False
 
+    ..
     """
     def __init__(self, name, mapset='', *args, **kwargs):
         super(VectorTopo, self).__init__(name, mapset, *args, **kwargs)
@@ -284,16 +278,20 @@ class VectorTopo(Vector):
 
     @must_be_open
     def num_primitive_of(self, primitive):
-        """Primitive are:
+        """Return the number of primitive
 
-            * "boundary",
-            * "centroid",
-            * "face",
-            * "kernel",
-            * "line",
-            * "point"
-            * "area"
-            * "volume"
+        :param primitive: the name of primitive to query; the supported values are:
+
+                            * *boundary*,
+                            * *centroid*,
+                            * *face*,
+                            * *kernel*,
+                            * *line*,
+                            * *point*
+                            * *area*
+                            * *volume*
+
+        :type primitive: str
 
         ::
 
@@ -316,10 +314,13 @@ class VectorTopo(Vector):
 
     @must_be_open
     def number_of(self, vtype):
-        """
-        vtype in ["areas", "dblinks", "faces", "holes", "islands", "kernels",
-                  "line_points", "lines", "nodes", "update_lines",
-                  "update_nodes", "volumes"]
+        """Return the number of the choosen element type
+
+        :param vtype: the name of type to query; the supported values are:
+                      *areas*, *dblinks*, *faces*, *holes*, *islands*,
+                      *kernels*, *line_points*, *lines*, *nodes*,
+                      *update_lines*, *update_nodes*, *volumes*
+        :type vtype: str
 
             >>> cens = VectorTopo('boundary_municp_sqlite')
             >>> cens.open()
@@ -365,7 +366,15 @@ class VectorTopo(Vector):
     def viter(self, vtype, idonly=False):
         """Return an iterator of vector features
 
-        ::
+        :param vtype: the name of type to query; the supported values are:
+                      *areas*, *dblinks*, *faces*, *holes*, *islands*,
+                      *kernels*, *line_points*, *lines*, *nodes*,
+                      *update_lines*, *update_nodes*, *volumes*
+        :type vtype: str
+        :param idonly: variable to return only the id of features instead of
+                       full features
+        :type idonly: bool
+
             >>> cens = VectorTopo('census')
             >>> cens.open()
             >>> big = [area for area in cens.viter('areas')
@@ -385,7 +394,6 @@ class VectorTopo(Vector):
             Area(2552) 298356117.948
             >>> cens.close()
 
-        ..
         """
         if vtype in _GEOOBJ.keys():
             if _GEOOBJ[vtype] is not None:
@@ -425,16 +433,15 @@ class VectorTopo(Vector):
     def cat(self, cat_id, vtype, layer=None, generator=False, geo=None):
         """Return the geometry features with category == cat_id.
 
-        Parameters
-        ----------
-        cat_id : integer
-            Integer with the category number.
-        vtype : string
-            String of the type of geometry feature that we are looking for.
-        layer : integer, optional
-            Integer of the layer that will be used.
-        generator : bool, optional
-            If True return a generator otherwise it return a list of features.
+        :param cat_id: the category number
+        :type cat_id: int
+        :param vtype: the type of geometry feature that we are looking for
+        :type vtype: str
+        :param layer: the layer number that will be used
+        :type layer: int
+        :param generator: if True return a generator otherwise it return a
+                          list of features
+        :type generator: bool
         """
         if geo is None and vtype not in _GEOOBJ:
             keys = "', '".join(sorted(_GEOOBJ.keys()))
@@ -455,7 +462,11 @@ class VectorTopo(Vector):
 
     @must_be_open
     def read(self, feature_id):
-        """Return a geometry object given the feature id. ::
+        """Return a geometry object given the feature id.
+
+            :param feature_id: the id of feature to obtain
+            :type feature_id: int
+
 
             >>> mun = VectorTopo('boundary_municp_sqlite')
             >>> mun.open()
@@ -480,7 +491,6 @@ class VectorTopo(Vector):
             IndexError: Index out of range
             >>> mun.close()
 
-        ..
         """
         return read_line(feature_id, self.c_mapinfo, self.table, self.writable)
 
@@ -504,7 +514,9 @@ class VectorTopo(Vector):
             attr = [line, ]
             attr.extend(attrs)
             self.table.update(key=line, values=attr)
-
+        elif self.table is None and attrs:
+            print "Table for vector {name} does not exist, attributes not" \
+                  " loaded".format(name=self.name) 
         libvect.Vect_cat_set(geo_obj.c_cats, self.layer, line)
         result = libvect.Vect_rewrite_line(self.c_mapinfo,
                                            line, geo_obj.gtype,
@@ -518,6 +530,11 @@ class VectorTopo(Vector):
 
     @must_be_open
     def delete(self, feature_id):
+        """Remove a feature by its id
+
+        :param feature_id: the id of the feature
+        :type feature_id: int
+        """
         if libvect.Vect_rewrite_line(self.c_mapinfo, feature_id) == -1:
             raise GrassError("C funtion: Vect_rewrite_line.")
 
@@ -541,8 +558,9 @@ class VectorTopo(Vector):
 
     @must_be_open
     def select_by_bbox(self, bbox):
-        """Return the BBox of the vecor map
+        """Return the BBox of the vector map
         """
+        # TODO replace with bbox if bbox else Bbox() ??
         bbox = Bbox()
         if libvect.Vect_get_map_box(self.c_mapinfo, bbox.c_bbox) == 0:
             raise GrassError("I can not find the Bbox.")

lib/python/pygrass/vector/abstract.py

@@ -111,18 +111,20 @@ class Info(object):
             self.rename(newname)
         self._name = newname
 
-    name = property(fget=_get_name, fset=_set_name)
+    name = property(fget=_get_name, fset=_set_name,
+                    doc="Set or obtain the Vector name")
 
     def _get_mapset(self):
-        """Private method to obtain the Vector name"""
+        """Private method to obtain the Vector mapset"""
         return self._mapset
 
     def _set_mapset(self, mapset):
-        """Private method to change the Vector name"""
+        """Private method to change the Vector mapset"""
         if mapset:
             self._mapset = mapset
 
-    mapset = property(fget=_get_mapset, fset=_set_mapset)
+    mapset = property(fget=_get_mapset, fset=_set_mapset,
+                      doc="Set or obtain the Vector mapset")
 
     def _get_organization(self):
         """Private method to obtain the Vector organization"""
@@ -132,7 +134,8 @@ class Info(object):
         """Private method to change the Vector organization"""
         libvect.Vect_get_organization(self.c_mapinfo, ctypes.c_char_p(org))
 
-    organization = property(fget=_get_organization, fset=_set_organization)
+    organization = property(fget=_get_organization, fset=_set_organization,
+                            doc="Set or obtain the Vector organization")
 
     def _get_date(self):
         """Private method to obtain the Vector date"""
@@ -142,7 +145,8 @@ class Info(object):
         """Private method to change the Vector date"""
         return libvect.Vect_set_date(self.c_mapinfo, ctypes.c_char_p(date))
 
-    date = property(fget=_get_date, fset=_set_date)
+    date = property(fget=_get_date, fset=_set_date,
+                    doc="Set or obtain the Vector date")
 
     def _get_person(self):
         """Private method to obtain the Vector person"""
@@ -152,7 +156,8 @@ class Info(object):
         """Private method to change the Vector person"""
         libvect.Vect_set_person(self.c_mapinfo, ctypes.c_char_p(person))
 
-    person = property(fget=_get_person, fset=_set_person)
+    person = property(fget=_get_person, fset=_set_person,
+                      doc="Set or obtain the Vector author")
 
     def _get_title(self):
         """Private method to obtain the Vector title"""
@@ -162,7 +167,8 @@ class Info(object):
         """Private method to change the Vector title"""
         libvect.Vect_set_map_name(self.c_mapinfo, ctypes.c_char_p(title))
 
-    title = property(fget=_get_title, fset=_set_title)
+    title = property(fget=_get_title, fset=_set_title,
+                     doc="Set or obtain the Vector title")
 
     def _get_map_date(self):
         """Private method to obtain the Vector map date"""
@@ -174,7 +180,8 @@ class Info(object):
         date_str = datetimeobj.strftime(self.date_fmt)
         libvect.Vect_set_map_date(self.c_mapinfo, ctypes.c_char_p(date_str))
 
-    map_date = property(fget=_get_map_date, fset=_set_map_date)
+    map_date = property(fget=_get_map_date, fset=_set_map_date,
+                        doc="Set or obtain the Vector map date")
 
     def _get_scale(self):
         """Private method to obtain the Vector scale"""
@@ -184,7 +191,8 @@ class Info(object):
         """Private method to set the Vector scale"""
         return libvect.Vect_set_scale(self.c_mapinfo, ctypes.c_int(scale))
 
-    scale = property(fget=_get_scale, fset=_set_scale)
+    scale = property(fget=_get_scale, fset=_set_scale,
+                     doc="Set or obtain the Vector scale")
 
     def _get_comment(self):
         """Private method to obtain the Vector comment"""
@@ -194,7 +202,8 @@ class Info(object):
         """Private method to set the Vector comment"""
         return libvect.Vect_set_comment(self.c_mapinfo, ctypes.c_char_p(comm))
 
-    comment = property(fget=_get_comment, fset=_set_comment)
+    comment = property(fget=_get_comment, fset=_set_comment,
+                       doc="Set or obtain the Vector comment")
 
     def _get_zone(self):
         """Private method to obtain the Vector projection zone"""
@@ -204,7 +213,8 @@ class Info(object):
         """Private method to set the Vector projection zone"""
         return libvect.Vect_set_zone(self.c_mapinfo, ctypes.c_int(zone))
 
-    zone = property(fget=_get_zone, fset=_set_zone)
+    zone = property(fget=_get_zone, fset=_set_zone,
+                    doc="Set or obtain the Vector projection zone")
 
     def _get_proj(self):
         """Private method to obtain the Vector projection code"""
@@ -214,7 +224,8 @@ class Info(object):
         """Private method to set the Vector projection code"""
         libvect.Vect_set_proj(self.c_mapinfo, ctypes.c_int(proj))
 
-    proj = property(fget=_get_proj, fset=_set_proj)
+    proj = property(fget=_get_proj, fset=_set_proj,
+                    doc="Set or obtain the Vector projection code")
 
     def _get_thresh(self):
         """Private method to obtain the Vector threshold"""
@@ -224,7 +235,8 @@ class Info(object):
         """Private method to set the Vector threshold"""
         return libvect.Vect_set_thresh(self.c_mapinfo, ctypes.c_double(thresh))
 
-    thresh = property(fget=_get_thresh, fset=_set_thresh)
+    thresh = property(fget=_get_thresh, fset=_set_thresh,
+                      doc="Set or obtain the Vector threshold")
 
     @property
     @must_be_open
@@ -248,7 +260,11 @@ class Info(object):
         libvect.Vect_write_header(self.c_mapinfo)
 
     def rename(self, newname):
-        """Method to rename the Vector map"""
+        """Method to rename the Vector map
+
+        :param newname: the new name for the Vector map
+        :type newname: str
+        """
         if self.exist():
             if not self.is_open():
                 functions.rename(self.name, newname, 'vect')
@@ -282,34 +298,34 @@ class Info(object):
              link_driver='sqlite'):
         """Open a Vector map.
 
-         Parameters
-        ----------
-        mode : string
-            Open a vector map in ``r`` in reading, ``w`` in writing and
-            in ``rw`` read and write mode
-        layer: int, optional
-            Specify the layer that you want to use
-
-        Some parameters are valid only if we open use the writing mode (``w``)
-
-        overwrite: bool, optional
-            valid only for ``w`` mode
-        tab_name: string, optional
-            Define the name of the table that will be generate
-        tab_cols: list of pairs, optional
-            Define the name and type of the columns of the attribute table
-            of the vecto map
-        link_name: string, optional
-            Define the name of the link connecttion with the database
-        link_key: string, optional
-            Define the nema of the column that will be use as vector category
-        link_db: string, optional
-            Define the database connection parameters
-        link_driver: string, optional
-            Define witch database driver will be used
+         
+        :param mode: open a vector map in ``r`` in reading, ``w`` in writing
+                     and in ``rw`` read and write mode
+        :type mode: str
+        :param layer: specify the layer that you want to use
+        :type layer: int
+        :param overwrite: valid only for ``w`` mode
+        :type overwrite: bool
+        :param tab_name: define the name of the table that will be generate
+        :type tab_name: str
+        :param tab_cols: define the name and type of the columns of the
+                         attribute table of the vecto map
+        :type tab_cols: list of pairs
+        :param link_name: define the name of the link connecttion with the
+                          database
+        :type link_name: str
+        :param link_key: define the nema of the column that will be use as
+                         vector category
+        :type link_key: str
+        :param link_db: define the database connection parameters
+        :type link_db: str
+        :param link_driver: define witch database driver will be used
+        :param link_driver: str
+
+        Some of the parameters are valid only with mode ``w`` or ``rw``
 
         See more examples in the documentation of the ``read`` and ``write``
-        methods.
+        methods
         """
         self.mode = mode if mode else self.mode
         # check if map exists or not
@@ -377,7 +393,11 @@ class Info(object):
                                                  self.writable), }
 
     def close(self, build=False):
-        """Method to close the Vector"""
+        """Method to close the Vector
+
+        :param build: True if the vector map should be build before close it
+        :type build: bool
+        """
         if hasattr(self, 'table') and self.table is not None:
             self.table.conn.close()
         if self.is_open():

lib/python/pygrass/vector/basic.py

@@ -55,7 +55,8 @@ class Bbox(object):
         """Private method to set the north value"""
         self.c_bbox.contents.N = value
 
-    north = property(fget=_get_n, fset=_set_n)
+    north = property(fget=_get_n, fset=_set_n,
+                     doc="Set and obtain north value")
 
     def _get_s(self):
         """Private method to obtain the south value"""
@@ -65,7 +66,8 @@ class Bbox(object):
         """Private method to set the south value"""
         self.c_bbox.contents.S = value
 
-    south = property(fget=_get_s, fset=_set_s)
+    south = property(fget=_get_s, fset=_set_s,
+                     doc="Set and obtain south value")
 
     def _get_e(self):
         """Private method to obtain the east value"""
@@ -75,7 +77,8 @@ class Bbox(object):
         """Private method to set the east value"""
         self.c_bbox.contents.E = value
 
-    east = property(fget=_get_e, fset=_set_e)
+    east = property(fget=_get_e, fset=_set_e,
+                    doc="Set and obtain east value")
 
     def _get_w(self):
         """Private method to obtain the west value"""
@@ -85,7 +88,8 @@ class Bbox(object):
         """Private method to set the west value"""
         self.c_bbox.contents.W = value
 
-    west = property(fget=_get_w, fset=_set_w)
+    west = property(fget=_get_w, fset=_set_w,
+                    doc="Set and obtain west value")
 
     def _get_t(self):
         """Private method to obtain the top value"""
@@ -95,7 +99,8 @@ class Bbox(object):
         """Private method to set the top value"""
         self.c_bbox.contents.T = value
 
-    top = property(fget=_get_t, fset=_set_t)
+    top = property(fget=_get_t, fset=_set_t,
+                   doc="Set and obtain top value")
 
     def _get_b(self):
         """Private method to obtain the bottom value"""
@@ -105,7 +110,8 @@ class Bbox(object):
         """Private method to set the bottom value"""
         self.c_bbox.contents.B = value
 
-    bottom = property(fget=_get_b, fset=_set_b)
+    bottom = property(fget=_get_b, fset=_set_b,
+                      doc="Set and obtain bottom value")
 
     def __repr__(self):
         return "Bbox({n}, {s}, {e}, {w})".format(n=self.north, s=self.south,
@@ -119,15 +125,16 @@ class Bbox(object):
         return ['north', 'south', 'west', 'east', 'top', 'bottom']
 
     def contains(self, point):
-        """Return True if the object is contained by the BoundingBox. ::
+        """Return True if the object is contained by the BoundingBox.
 
+        :param point:the point to analyze 
+        :type point: a Point object or a tuple with the coordinates
             >>> from grass.pygrass.vector.geometry import Point
             >>> poi = Point(5,5)
             >>> bbox = Bbox(north=10, south=0, west=0, east=10)
             >>> bbox.contains(poi)
             True
 
-        ..
         """
         return bool(libvect.Vect_point_in_box(point.x, point.y,
                                               point.z if point.z else 0,
@@ -137,10 +144,11 @@ class Bbox(object):
         return [(k, self.__getattribute__(k)) for k in self.keys()]
 
     def nsewtb(self, tb=True):
-        """Return a list
+        """Return a list of values from bounding box
 
-        If tb parameter is False return only:
-        north, south, east, west
+        :param tb: if tb parameter is False return only: north, south, east,
+                   west and not top and bottom
+        :type tb: bool
         """
         if tb:
             return (self.north, self.south, self.east, self.west,
@@ -193,8 +201,11 @@ class BoxList(object):
 
     def append(self, box):
         """Append a Bbox object to a Boxlist object, using the
-        ``Vect_boxlist_append`` C fuction. ::
-
+        ``Vect_boxlist_append`` C fuction. 
+        
+        :param bbox: the bounding box to add to the list
+        :param bbox: a Bbox object
+        
             >>> box0 = Bbox()
             >>> box1 = Bbox(1,2,3,4)
             >>> box2 = Bbox(5,6,7,8)
@@ -207,7 +218,6 @@ class BoxList(object):
             >>> len(boxlist)
             3
 
-        ..
         """
         indx = self.__len__()
         libvect.Vect_boxlist_append(self.c_boxlist, indx, box.c_bbox)
@@ -247,8 +257,10 @@ class BoxList(object):
     def remove(self, indx):
         """Remove Bbox from the boxlist, given an integer or a list of integer
         or a boxlist, using ``Vect_boxlist_delete`` C function or the
-        ``Vect_boxlist_delete_boxlist``. ::
+        ``Vect_boxlist_delete_boxlist``.
 
+        :param indx: the index value of the Bbox to remove
+        :param indx: int
             >>> boxlist = BoxList([Bbox(),
             ...                    Bbox(1, 0, 0, 1),
             ...                    Bbox(1, -1, -1, 1)])
@@ -256,7 +268,6 @@ class BoxList(object):
             >>> boxlist
             Boxlist([Bbox(1.0, 0.0, 0.0, 1.0), Bbox(1.0, -1.0, -1.0, 1.0)])
 
-        ..
         """
         if hasattr(indx, 'c_boxlist'):
             libvect.Vect_boxlist_delete_boxlist(self.c_boxlist, indx.c_boxlist)
@@ -335,7 +346,11 @@ class Ilist(object):
 
     def extend(self, ilist):
         """Extend the list with another Ilist object or
-        with a list of integers"""
+        with a list of integers
+
+        :param ilist: the ilist to append
+        :type ilist: a Ilist object        
+        """
         if isinstance(ilist, Ilist):
             libvect.Vect_list_append_list(self.c_ilist, ilist.ilist)
         else:
@@ -416,19 +431,34 @@ class Cats(object):
 
     def get(self, layer=1):
         """Return the first found category of given layer
-        and the number of category found. """
+        and the number of category found.
+
+        :param layer: the number of layer
+        :type layer: int
+        """
         cat = ctypes.c_int()
         n_cats = libvect.Vect_cat_get(self.c_cats, layer, ctypes.byref(cat))
         return cat.value, n_cats
 
     def set(self, cat, layer=1):
-        """Add new field/cat to category structure if doesn't exist yet."""
+        """Add new field/cat to category structure if doesn't exist yet.
+
+        :param cat: the cat to add
+        :type cat: int
+        :param layer: the number of layer
+        :type layer: int
+        """
         libvect.Vect_cat_set(self.c_cats, layer, cat)
 
     def delete(self, cat=None, layer=1):
         """If cat is given delete cat from line_cats structure
         (using Vect_field_cat_del) else delete all categories of given layer
         (using Vect_cat_del).
+
+        :param cat: the cat to add
+        :type cat: int
+        :param layer: the number of layer
+        :type layer: int
         """
         if cat:
             self.n_del = libvect.Vect_field_cat_del(self.c_cats, layer, cat)
@@ -441,12 +471,22 @@ class Cats(object):
             raise ValueError(err_msg)
 
     def check_cats_constraints(self, cats_list, layer=1):
-        """Check if categories match with category constraints"""
+        """Check if categories match with category constraints
+
+        :param cats_list: a list of categories
+        :type cats_list: list
+        :param layer: the number of layer
+        :type layer: int
+        """
         return bool(libvect.Vect_cats_in_constraint(self.c_cats, layer,
                                                     cats_list.c_cat_list))
 
     def get_list(self, layer=1):
-        """Get list of categories of given field."""
+        """Get list of categories of given field.
+
+        :param layer: the number of layer
+        :type layer: int
+        """
         ilist = Ilist()
         if libvect.Vect_field_cat_get(self.c_cats, layer,
                                       ilist.c_ilist) < 0:
@@ -504,19 +544,30 @@ class CatsList(object):
 
     def from_string(self, string):
         """Converts string of categories and cat ranges separated by commas
-        to cat_list."""
+        to cat_list.
+
+        :param string: a string containing the cats separated by commas
+        :type string: str
+        """
         num_errors = libvect.Vect_str_to_cat_list(string, self.c_cat_list)
         if num_errors:
             from grass.pygrass.errors import GrassError
             raise GrassError("%d number of errors in ranges" % num_errors)
 
     def from_array(self, array):
-        """Convert ordered array of integers to cat_list structure."""
+        """Convert ordered array of integers to cat_list structure.
+
+        :param array: the input array containing the cats
+        :type array: array
+        """
         # Vect_array_to_cat_list(const int *vals, int nvals, ***)
         # TODO: it's not working
         libvect.Vect_array_to_cat_list(array, len(array), self.c_cat_list)
 
     def __contains__(self, cat):
         """Check if category number is in list.
-        int 	Vect_cat_in_cat_list (int cat, const struct cat_list *list)"""
+
+        :param cat: the category number
+        :type cat: int
+        """
         return bool(libvect.Vect_cat_in_cat_list(cat, self.c_cat_list))

lib/python/pygrass/vector/geometry.py

@@ -143,7 +143,8 @@ class Attrs(object):
             # update condition
             self.cond = "%s=%d" % (self.table.key, value)
 
-    cat = property(fget=_get_cat, fset=_set_cat)
+    cat = property(fget=_get_cat, fset=_set_cat,
+                   doc="Set and obtain cat value")
 
     def __getitem__(self, key):
         """Return the value stored in the attribute table. ::
@@ -342,7 +343,8 @@ class Point(Geo):
     def _set_x(self, value):
         self.c_points.contents.x[0] = value
 
-    x = property(fget=_get_x, fset=_set_x)
+    x = property(fget=_get_x, fset=_set_x,
+                 doc="Set and obtain x coordinate")
 
     def _get_y(self):
         return self.c_points.contents.y[0]
@@ -350,7 +352,8 @@ class Point(Geo):
     def _set_y(self, value):
         self.c_points.contents.y[0] = value
 
-    y = property(fget=_get_y, fset=_set_y)
+    y = property(fget=_get_y, fset=_set_y,
+                 doc="Set and obtain y coordinate")
 
     def _get_z(self):
         if self.is2D:
@@ -365,7 +368,8 @@ class Point(Geo):
             self.c_points.contents.z[0] = value
             self.is2D = False
 
-    z = property(fget=_get_z, fset=_set_z)
+    z = property(fget=_get_z, fset=_set_z,
+                 doc="Set and obtain z coordinate")
 
     def __str__(self):
         return self.get_wkt()
@@ -429,7 +433,10 @@ class Point(Geo):
     def distance(self, pnt):
         """Calculate distance of 2 points, using the Vect_points_distance
         C function, If one of the point have z == None, return the 2D distance.
-        ::
+
+        :param pnt: the point for calculate the distance
+        :type pnt: a Point object or a tuple with the coordinates
+
 
             >>> pnt0 = Point(0, 0, 0)
             >>> pnt1 = Point(1, 0)
@@ -441,8 +448,6 @@ class Point(Geo):
             >>> pnt0.distance(pnt1)
             1.4142135623730951
 
-        The distance method require a :class:Point or a tuple with
-        the coordinates.
         """
         if self.is2D or pnt.is2D:
             return libvect.Vect_points_distance(self.x, self.y, 0,
@@ -456,31 +461,21 @@ class Point(Geo):
         """Return the buffer area around the point, using the
         ``Vect_point_buffer2`` C function.
 
-        Parameters
-        ----------
-        dist : numeric
-            The distance around the line.
-        dist_x: numeric, optional
-            The distance along x
-        dist_y: numeric, optional
-            The distance along y
-        angle: numeric, optional
-            The angle between 0x and major axis
-        round_: bool, optional
-            To make corners round
-        tol: float, optional
-            Fix the maximum distance between theoretical arc
-            and output segments
-
-        Returns
-        -------
-        buffer : Area
-            The buffer area around the line.
-
-        Example
-        ---------
+        :param dist: the distance around the point
+        :type dist: num
+        :param dist_x: the distance along x
+        :type dist_x: num
+        :param dist_y: the distance along y
+        :type dist_y: num
+        :param angle: the angle between 0x and major axis
+        :type angle: num
+        :param round_: to make corners round
+        :type round_: bool
+        :param tol: fix the maximum distance between theoretical arc and
+                    output segments
+        :type tol: float
+        :returns: the buffer as Area object
 
-        ::
             >>> pnt = Point(0, 0)
             >>> area = pnt.buffer(10)
             >>> area.boundary                              #doctest: +ELLIPSIS
@@ -623,7 +618,10 @@ class Line(Geo):
 
     def append(self, pnt):
         """Appends one point to the end of a line, using the
-        ``Vect_append_point`` C function. ::
+        ``Vect_append_point`` C function.
+        
+        :param pnt: the point to add to line
+        :type pnt: a Point object or a tuple with the coordinates
 
             >>> line = Line()
             >>> line.append((10, 100))
@@ -656,11 +654,13 @@ class Line(Geo):
     def extend(self, line, forward=True):
         """Appends points to the end of a line.
 
-        It is possible to extend a line, give a list of points, or directly
-        with a line_pnts struct.
-
-        If forward is True the line is extend forward otherwise is extend
-        backward. The method use the `Vect_append_points` C function. ::
+        :param line: it is possible to extend a line, give a list of points,
+                     or directly with a line_pnts struct.
+        :type line: Line object ot list of points
+        :param forward: if forward is True the line is extend forward otherwise
+                        is extend backward. The method use the
+                        `Vect_append_points` C function.
+        :type forward: bool
 
             >>> line = Line([(0, 0), (1, 1)])
             >>> line.extend( Line([(2, 2), (3, 3)]) )
@@ -670,8 +670,6 @@ class Line(Geo):
                   Point(2.000000, 2.000000),
                   Point(3.000000, 3.000000)])
 
-        Like python list, it is possible to extend a line, with another line
-        or with a list of points.
         """
         # set direction
         if forward:
@@ -694,7 +692,12 @@ class Line(Geo):
     def insert(self, indx, pnt):
         """Insert new point at index position and move all old points at
         that position and above up, using ``Vect_line_insert_point``
-        C function. ::
+        C function.
+
+        :param indx: the index where add new point
+        :type indx: int
+        :param pnt: the point to add
+        :type pnt: a Point object
 
             >>> line = Line([(0, 0), (1, 1)])
             >>> line.insert(0, Point(1.000000, -1.000000) )
@@ -703,7 +706,6 @@ class Line(Geo):
                   Point(0.000000, 0.000000),
                   Point(1.000000, 1.000000)])
 
-        ..
         """
         if indx < 0:  # Handle negative indices
             indx += self.c_points.contents.n_points
@@ -737,7 +739,12 @@ class Line(Geo):
         return libvect.Vect_line_geodesic_length(self.c_points)
 
     def distance(self, pnt):
-        """Return a tuple with:
+        """Calculate the distance between line and a point. 
+        
+        :param pnt: the point to calculate distance
+        :type pnt: a Point object or a tuple with the coordinates
+        
+        Return a tuple with:
 
             * the closest point on the line,
             * the distance between these two points,
@@ -746,15 +753,10 @@ class Line(Geo):
 
         The distance is compute using the ``Vect_line_distance`` C function.
 
-        Example
-        ---------
-
-        ::
             >>> line = Line([(0, 0), (0, 2)])
             >>> line.distance(Point(1, 1))
             (Point(0.000000, 1.000000), 1.0, 1.0, 1.0)
 
-        ..
         """
         # instantite outputs
         cx = ctypes.c_double(0)
@@ -789,7 +791,10 @@ class Line(Geo):
         pass
 
     def pop(self, indx):
-        """Return the point in the index position and remove from the Line. ::
+        """Return the point in the index position and remove from the Line.
+
+           :param indx: the index where add new point
+           :type indx: int
 
             >>> line = Line([(0, 0), (1, 1), (2, 2)])
             >>> midle_pnt = line.pop(1)
@@ -798,7 +803,6 @@ class Line(Geo):
             >>> line
             Line([Point(0.000000, 0.000000), Point(2.000000, 2.000000)])
 
-        ..
         """
         if indx < 0:  # Handle negative indices
             indx += self.c_points.contents.n_points
@@ -809,14 +813,15 @@ class Line(Geo):
         return pnt
 
     def delete(self, indx):
-        """Remove the point in the index position. ::
+        """Remove the point in the index position.
+           :param indx: the index where add new point
+           :type indx: int
 
             >>> line = Line([(0, 0), (1, 1), (2, 2)])
             >>> line.delete(-1)
             >>> line
             Line([Point(0.000000, 0.000000), Point(1.000000, 1.000000)])
 
-        ..
         """
         if indx < 0:  # Handle negative indices
             indx += self.c_points.contents.n_points
@@ -841,7 +846,10 @@ class Line(Geo):
 
     def prune_thresh(self, threshold):
         """Remove points in threshold, using the ``Vect_line_prune_thresh``
-        C funtion. ::
+        C funtion.
+        
+        :param threshold: the threshold value where prune points
+        :type threshold: num
 
             >>> line = Line([(0, 0), (1.0, 1.0), (1.2, 0.9), (2, 2)])
             >>> line.prune_thresh(0.5)
@@ -858,7 +866,10 @@ class Line(Geo):
 
     def remove(self, pnt):
         """Delete point at given index and move all points above down, using
-        `Vect_line_delete_point` C function. ::
+        `Vect_line_delete_point` C function.
+        
+        :param pnt: the point to remove
+        :type pnt: a Point object or a tuple with the coordinates
 
             >>> line = Line([(0, 0), (1, 1), (2, 2)])
             >>> line.remove((2, 2))
@@ -889,7 +900,9 @@ class Line(Geo):
         libvect.Vect_line_reverse(self.c_points)
 
     def segment(self, start, end):
-        """Create line segment. using the ``Vect_line_segment`` C function."""
+        # TODO improve documentation
+        """Create line segment. using the ``Vect_line_segment`` C function.
+        """
         line = Line()
         libvect.Vect_line_segment(self.c_points, start, end, line.c_points)
         return line
@@ -933,7 +946,10 @@ class Line(Geo):
                for pnt in self.__iter__()])
 
     def from_wkt(self, wkt):
-        """Read a WKT string. ::
+        """Create a line reading a WKT string.
+
+        :param wkt: the WKT string containing the LINESTRING
+        :type wkt: str
 
             >>> line = Line()
             >>> line.from_wkt("LINESTRING(0 0,1 1,1 2)")
@@ -966,33 +982,21 @@ class Line(Geo):
         """Return the buffer area around the line, using the
         ``Vect_line_buffer2`` C function.
 
-        Parameters
-        ----------
-        dist : numeric
-            The distance around the line.
-        dist_x: numeric, optional
-            The distance along x
-        dist_y: numeric, optional
-            The distance along y
-        angle: numeric, optional
-            The angle between 0x and major axis
-        round_: bool, optional
-            To make corners round
-        caps: bool, optional
-            To add caps at line ends
-        tol: float, optional
-            Fix the maximum distance between theoretical arc
-            and output segments
-
-        Returns
-        -------
-        buffer : Area
-            The buffer area around the line.
-
-        Example
-        ---------
+        :param dist: the distance around the line
+        :type dist: num
+        :param dist_x: the distance along x
+        :type dist_x: num
+        :param dist_y: the distance along y
+        :type dist_y: num
+        :param angle: the angle between 0x and major axis
+        :type angle: num
+        :param round_: to make corners round
+        :type round_: bool
+        :param tol: fix the maximum distance between theoretical arc and
+                    output segments
+        :type tol: float
+        :returns: the buffer as Area object
 
-        ::
             >>> line = Line([(0, 0), (0, 2)])
             >>> area = line.buffer(10)
             >>> area.boundary                              #doctest: +ELLIPSIS
@@ -1080,9 +1084,19 @@ class Boundary(Line):
                 return cntr
 
     def get_left_centroid(self, idonly=False):
+        """Return left value
+
+        :param idonly: True to return only the cat of feature
+        :type idonly: bool        
+        """
         return self._get_centroid(self.left_id, idonly)
 
     def get_right_centroid(self, idonly=False):
+        """Return right value
+
+        :param idonly: True to return only the cat of feature
+        :type idonly: bool
+        """
         return self._get_centroid(self.left_id, idonly)
 
     def get_left_right(self):
@@ -1094,13 +1108,13 @@ class Boundary(Line):
 
     def area(self):
         """Return the area of the polygon.
-        ::
+
             >>> bound = Boundary(points=[(0, 0), (0, 2), (2, 2), (2, 0),
             ...                          (0, 0)])
             >>> bound.area()
             4.0
 
-        .."""
+        """
         libgis.G_begin_polygon_area_calculations()
         return libgis.G_area_of_polygon(self.c_points.contents.x,
                                         self.c_points.contents.y,
@@ -1170,12 +1184,14 @@ class Isle(Geo):
         return "Isle(%d)" % (self.id)
 
     def boundaries(self):
+        """Return a list of boundaries"""
         ilist = Ilist()
         libvect.Vect_get_isle_boundaries(self.c_mapinfo, self.id,
                                          ilist.c_ilist)
         return ilist
 
     def bbox(self, bbox=None):
+        """Return bounding box of Isle"""
         bbox = bbox if bbox else Bbox()
         libvect.Vect_get_isle_box(self.c_mapinfo, self.id, bbox.c_bbox)
         return bbox
@@ -1200,7 +1216,11 @@ class Isle(Geo):
         return bool(libvect.Vect_isle_alive(self.c_mapinfo, self.id))
 
     def contain_pnt(self, pnt):
-        """Check if point is in area."""
+        """Check if point is in area.
+
+        :param pnt: the point to remove
+        :type pnt: a Point object or a tuple with the coordinates
+        """
         bbox = self.bbox()
         return bool(libvect.Vect_point_in_island(pnt.x, pnt.y,
                                                  self.c_mapinfo, self.id,
@@ -1245,15 +1265,22 @@ class Isles(object):
         return self._isles[key]
 
     def get_isles_id(self):
+        """Return the id of isles"""
         return [libvect.Vect_get_area_isle(self.c_mapinfo, self.area_id, i)
                 for i in range(self.__len__())]
 
     def get_isles(self):
+        """Return isles"""
         return [Isle(v_id=isle_id, c_mapinfo=self.c_mapinfo)
                 for isle_id in self._isles_id]
 
     def select_by_bbox(self, bbox):
-        """Vect_select_isles_by_box"""
+        """Vect_select_isles_by_box
+
+        .. warning::
+
+            Not implemented yet.
+        """
         pass
 
 
@@ -1309,12 +1336,21 @@ class Area(Geo):
         self.get_isles()
 
     def get_points(self, line=None):
-        """Return a Line object with the outer ring"""
+        """Return a Line object with the outer ring
+
+        :param line: a Line object to fill with info from points of area
+        :type line: a Line object
+        """
         line = Line() if line is None else line
         libvect.Vect_get_area_points(self.c_mapinfo, self.id, line.c_points)
         return line
 
     def get_centroid(self, centroid=None):
+        """Return the centroid
+
+        :param centroid: a Centroid object to fill with info from centroid of area
+        :type centroid: a Centroid object
+        """
         centroid_id = libvect.Vect_get_area_centroid(self.c_mapinfo, self.id)
         if centroid:
             centroid.id = centroid_id
@@ -1346,8 +1382,10 @@ class Area(Geo):
         return bool(libvect.Vect_area_alive(self.c_mapinfo, self.id))
 
     def bbox(self, bbox=None):
-        """
-        Vect_get_area_box
+        """Return the Bbox of area
+
+        :param bbox: a Bbox object to fill with info from bounding box of area
+        :type bbox: a Bbox object
         """
         bbox = bbox if bbox else Bbox()
         libvect.Vect_get_area_box(self.c_mapinfo, self.id, bbox.c_bbox)
@@ -1358,28 +1396,20 @@ class Area(Geo):
         """Return the buffer area around the area, using the
         ``Vect_area_buffer2`` C function.
 
-        Parameters
-        ----------
-        dist : numeric
-            The distance around the line.
-        dist_x: numeric, optional
-            The distance along x
-        dist_y: numeric, optional
-            The distance along y
-        angle: numeric, optional
-            The angle between 0x and major axis
-        round_: bool, optional
-            To make corners round
-        caps: bool, optional
-            To add caps at line ends
-        tol: float, optional
-            Fix the maximum distance between theoretical arc
-            and output segments
-
-        Returns
-        -------
-        buffer : Area
-            The buffer area around the line.
+        :param dist: the distance around the area
+        :type dist: num
+        :param dist_x: the distance along x
+        :type dist_x: num
+        :param dist_y: the distance along y
+        :type dist_y: num
+        :param angle: the angle between 0x and major axis
+        :type angle: num
+        :param round_: to make corners round
+        :type round_: bool
+        :param tol: fix the maximum distance between theoretical arc and
+                    output segments
+        :type tol: float
+        :returns: the buffer as Area object
 
         """
         if dist is not None:
@@ -1415,8 +1445,9 @@ class Area(Geo):
 
     def cats(self, cats=None):
         """Get area categories.
-        int Vect_get_area_cats (const struct Map_info *Map,
-                                int area, struct line_cats *Cats)
+
+        :param cats: a Cats object to fill with info with area categories
+        :type cats: a Cats object
         """
         cats = cats if cats else Cats()
         libvect.Vect_get_area_cats(self.c_mapinfo, self.id, cats.c_cats)
@@ -1431,9 +1462,11 @@ class Area(Geo):
 
     def contain_pnt(self, pnt, bbox=None):
         """Check if point is in area.
-        int Vect_point_in_area(double x, double y,
-                               const struct Map_info *Map,
-                               int area, struct bound_box box)
+
+        :param pnt: the point to analyze 
+        :type pnt: a Point object or a tuple with the coordinates
+        :param bbox: the bounding box where run the analysis
+        :type bbox: a Bbox object
         """
         bbox = bbox if bbox else self.bbox()
         return bool(libvect.Vect_point_in_area(pnt.x, pnt.y,

lib/python/pygrass/vector/table.py

@@ -93,19 +93,32 @@ class Filters(object):
         return self
 
     def where(self, condition):
-        """Create the where condition"""
+        """Create the where condition
+
+        :param condition: the condition of where statement, for example
+                          `cat = 1`
+        :type condition: str
+        """
         self._where = 'WHERE {condition}'.format(condition=condition)
         return self
 
     def order_by(self, orderby):
-        """Create the order by condition"""
+        """Create the order by condition
+
+        :param orderby: the name of column/s to order the result
+        :type orderby: str
+        """
         if not isinstance(orderby, unicode):
             orderby = ', '.join(orderby)
         self._orderby = 'ORDER BY {orderby}'.format(orderby=orderby)
         return self
 
     def limit(self, number):
-        """Create the limit condition"""
+        """Create the limit condition
+
+        :param number: the number to limit the result
+        :type number: int
+        """
         if not isinstance(number, int):
             raise ValueError("Must be an integer.")
         else:
@@ -113,7 +126,11 @@ class Filters(object):
         return self
 
     def group_by(self, groupby):
-        """Create the group by condition"""
+        """Create the group by condition
+
+        :param groupby: the name of column/s to group the result
+        :type groupby: str, list
+        """
         if not isinstance(groupby, unicode):
             groupby = ', '.join(groupby)
         self._groupby = 'GROUP BY {groupby}'.format(groupby=groupby)
@@ -347,7 +364,13 @@ class Columns(object):
         return self.odict.items()
 
     def add(self, col_name, col_type):
-        """Add a new column to the table. ::
+        """Add a new column to the table.
+
+        :param col_name: the name of column to add
+        :type col_name: str
+        :param col_type: the tipe of column to add
+        :type col_type: str
+        ::
 
             >>> import sqlite3
             >>> path = '$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db'
@@ -369,6 +392,11 @@ class Columns(object):
         ..
         """
         def check_col(col_type):
+            """Check the column type if it is supported by GRASS
+            
+            :param col_type: the type of column
+            :type col_type: str            
+            """
             valid_type = ('DOUBLE PRECISION', 'DOUBLE', 'INT', 'INTEGER',
                           'DATE')
             if 'VARCHAR' in col_type or col_type.upper() not in valid_type:
@@ -397,7 +425,13 @@ class Columns(object):
         self.update_odict()
 
     def rename(self, old_name, new_name):
-        """Rename a column of the table. ::
+        """Rename a column of the table.
+
+        :param old_name: the name of existing column
+        :type old_name: str
+        :param new_name: the name of new column
+        :type new_name: str
+        ::
 
             >>> import sqlite3
             >>> path = '$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db'
@@ -447,7 +481,13 @@ class Columns(object):
             self.drop(old_name)
 
     def cast(self, col_name, new_type):
-        """Change the column type. ::
+        """Change the column type.
+
+        :param col_name: the name of column
+        :type col_name: str
+        :param new_type: the new type of column
+        :type new_type: str
+        ::
 
             >>> import sqlite3
             >>> path = '$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db'
@@ -485,7 +525,11 @@ class Columns(object):
             raise DBError('SQLite does not support to cast columns.')
 
     def drop(self, col_name):
-        """Drop a column from the table. ::
+        """Drop a column from the table.
+
+        :param col_name: the name of column to remove
+        :type col_name: str
+        ::
 
             >>> import sqlite3
             >>> path = '$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db'
@@ -582,7 +626,8 @@ class Link(object):
             raise TypeError("Number must be positive and greater than 0.")
         self.c_fieldinfo.contents.number = number
 
-    layer = property(fget=_get_layer, fset=_set_layer)
+    layer = property(fget=_get_layer, fset=_set_layer,
+                     doc="Set and obtain layer number")
 
     def _get_name(self):
         return self.c_fieldinfo.contents.name
@@ -590,7 +635,8 @@ class Link(object):
     def _set_name(self, name):
         self.c_fieldinfo.contents.name = name
 
-    name = property(fget=_get_name, fset=_set_name)
+    name = property(fget=_get_name, fset=_set_name,
+                    doc="Set and obtain name vale")
 
     def _get_table(self):
         return self.c_fieldinfo.contents.table
@@ -598,7 +644,8 @@ class Link(object):
     def _set_table(self, new_name):
         self.c_fieldinfo.contents.table = new_name
 
-    table_name = property(fget=_get_table, fset=_set_table)
+    table_name = property(fget=_get_table, fset=_set_table,
+                          doc="Set and obtain table name value")
 
     def _get_key(self):
         return self.c_fieldinfo.contents.key
@@ -606,7 +653,8 @@ class Link(object):
     def _set_key(self, key):
         self.c_fieldinfo.contents.key = key
 
-    key = property(fget=_get_key, fset=_set_key)
+    key = property(fget=_get_key, fset=_set_key,
+                   doc="Set and obtain cat value")
 
     def _get_database(self):
         return self.c_fieldinfo.contents.database
@@ -614,7 +662,8 @@ class Link(object):
     def _set_database(self, database):
         self.c_fieldinfo.contents.database = database
 
-    database = property(fget=_get_database, fset=_set_database)
+    database = property(fget=_get_database, fset=_set_database,
+                        doc="Set and obtain database value")
 
     def _get_driver(self):
         return self.c_fieldinfo.contents.driver
@@ -625,7 +674,9 @@ class Link(object):
             raise TypeError(str_err)
         self.c_fieldinfo.contents.driver = driver
 
-    driver = property(fget=_get_driver, fset=_set_driver)
+    driver = property(fget=_get_driver, fset=_set_driver,
+                      doc="Set and obtain driver value. The drivers supported \
+                      by PyGRASS are: SQLite and PostgreSQL")
 
     def __init__(self, layer=1, name=None, table=None, key='cat',
                  database='$GISDBASE/$LOCATION_NAME/'
@@ -777,7 +828,11 @@ class DBlinks(object):
         return "DBlinks(%r)" % [link for link in self.__iter__()]
 
     def by_index(self, indx):
-        """Return a Link object by index"""
+        """Return a Link object by index
+
+        :param indx: the index where add new point
+        :type indx: int
+        """
         nlinks = self.num_dblinks()
         if nlinks == 0:
             raise IndexError
@@ -789,19 +844,33 @@ class DBlinks(object):
         return Link(c_fieldinfo=c_fieldinfo) if c_fieldinfo else None
 
     def by_layer(self, layer):
+        """Return the choosen Link using the layer
+
+        :param layer: the number of layer
+        :type layer: int
+        """
         c_fieldinfo = libvect.Vect_get_field(self.c_mapinfo, layer)
         return Link(c_fieldinfo=c_fieldinfo) if c_fieldinfo else None
 
     def by_name(self, name):
+        """Return the choosen Link using the name
+
+        :param name: the name of Link
+        :type name: str
+        """
         c_fieldinfo = libvect.Vect_get_field_by_name(self.c_mapinfo, name)
         return Link(c_fieldinfo=c_fieldinfo) if c_fieldinfo else None
 
     def num_dblinks(self):
+        """Return the number of DBlinks"""
         return libvect.Vect_get_num_dblinks(self.c_mapinfo)
 
     def add(self, link):
-        """Add a new link.
-           Need to open vector map in write mode::
+        """Add a new link. Need to open vector map in write mode
+
+           :param link: the Link to add to the DBlinks
+           :type link: a Link object
+           ::
 
             >>> from grass.pygrass.vector import VectorTopo
             >>> municip = VectorTopo('census')
@@ -883,7 +952,8 @@ class Table(object):
         self.conn.commit()
         cur.close()
 
-    name = property(fget=_get_name, fset=_set_name)
+    name = property(fget=_get_name, fset=_set_name,
+                    doc="Set and obtain table name")
 
     def __init__(self, name, connection, key='cat'):
         self._name = name
@@ -917,7 +987,7 @@ class Table(object):
         return self.n_rows()
 
     def drop(self, cursor=None, force=False):
-        """Private method to drop table from database"""
+        """Method to drop table from database"""
 
         cur = cursor if cursor else self.conn.cursor()
         if self.exist(cursor=cur):