[GRASS-SVN] r61155 - grass/trunk/lib/python/pygrass/modules/interface

[svn_grass at osgeo.org]

Author: zarch
Date: 2014-07-04 06:59:30 -0700 (Fri, 04 Jul 2014)
New Revision: 61155

Modified:
   grass/trunk/lib/python/pygrass/modules/interface/flag.py
Log:
pygrass: Add documentation

Modified: grass/trunk/lib/python/pygrass/modules/interface/flag.py
===================================================================
--- grass/trunk/lib/python/pygrass/modules/interface/flag.py	2014-07-04 12:46:09 UTC (rev 61154)
+++ grass/trunk/lib/python/pygrass/modules/interface/flag.py	2014-07-04 13:59:30 UTC (rev 61155)
@@ -1,19 +1,28 @@
 # -*- coding: utf-8 -*-
-"""
-Created on Tue Apr  2 18:39:21 2013
-
- at author: pietro
-"""
 from __future__ import (nested_scopes, generators, division, absolute_import,
                         with_statement, print_function, unicode_literals)
 from grass.pygrass.functions import docstring_property
 from grass.pygrass.modules.interface import read
 
-# TODO add documentation
+
 class Flag(object):
     """The Flag object store all information about a flag of module.
 
-    It is possible to set flags of command using this object.
+    It is possible to set flags of command using this object. ::
+
+            >>> flag = Flag(diz=dict(name='a', description='Flag description',
+            ...                      default=True))
+            >>> flag.name
+            u'a'
+            >>> flag.special
+            False
+            >>> flag.description
+            u'Flag description'
+            >>> flag = Flag(diz=dict(name='overwrite'))
+            >>> flag.name
+            u'overwrite'
+            >>> flag.special
+            True
     """
     def __init__(self, xflag=None, diz=None):
         self.value = False
@@ -26,7 +35,22 @@
         self.guisection = diz.get('guisection', None)
 
     def get_bash(self):
-        """Prova"""
+        """Return the BASH representation of a flag. ::
+
+            >>> flag = Flag(diz=dict(name='a', description='Flag description',
+            ...                      default=True))
+            >>> flag.get_bash()
+            u''
+            >>> flag.value = True
+            >>> flag.get_bash()
+            u'-a'
+            >>> flag = Flag(diz=dict(name='overwrite'))
+            >>> flag.get_bash()
+            u''
+            >>> flag.value = True
+            >>> flag.get_bash()
+            u'--o'
+        """
         if self.value:
             if self.special:
                 return '--%s' % self.name[0]
@@ -36,26 +60,56 @@
             return ''
 
     def get_python(self):
-        """Prova"""
+        """Return the python representation of a flag. ::
+
+            >>> flag = Flag(diz=dict(name='a', description='Flag description',
+            ...                      default=True))
+            >>> flag.get_python()
+            u''
+            >>> flag.value = True
+            >>> flag.get_python()
+            u'a'
+            >>> flag = Flag(diz=dict(name='overwrite'))
+            >>> flag.get_python()
+            u''
+            >>> flag.value = True
+            >>> flag.get_python()
+            u'overwrite=True'
+        """
         if self.value:
-            if self.special:
-                return '%s=True' % self.name
-            else:
-                return self.name
-        else:
-            return ''
+            return '%s=True' % self.name if self.special else self.name
+        return ''
 
     def __str__(self):
+        """Return the BASH representation of the flag."""
         return self.get_bash()
 
     def __repr__(self):
+        """Return a string with the python representation of the instance."""
         return "Flag <%s> (%s)" % (self.name, self.description)
 
     @docstring_property(__doc__)
     def __doc__(self):
+        """Return a documentation string, something like:
+
+        {name}: {default}
+            {description}
+
+        ::
+
+            >>>  flag = Flag(diz=dict(name='a', description='Flag description',
+            ...                      default=True))
+            >>> print(flag.__doc__)
+            a: True
+                Flag description
+
+            >>> flag = Flag(diz=dict(name='overwrite'))
+            >>> print(flag.__doc__)
+            overwrite: None
+                None
+
+        ..
         """
-        {name}: {default}
-            {description}"""
         return read.DOC['flag'].format(name=self.name,
                                        default=repr(self.default),
                                        description=self.description)