[GRASS-SVN] r65663 - grass/branches/releasebranch_7_0/lib/python/script

[svn_grass at osgeo.org]

Author: wenzeslaus
Date: 2015-07-19 12:23:39 -0700 (Sun, 19 Jul 2015)
New Revision: 65663

Modified:
   grass/branches/releasebranch_7_0/lib/python/script/core.py
Log:
backport r65612 (improve python doc)

Modified: grass/branches/releasebranch_7_0/lib/python/script/core.py
===================================================================
--- grass/branches/releasebranch_7_0/lib/python/script/core.py	2015-07-19 19:20:57 UTC (rev 65662)
+++ grass/branches/releasebranch_7_0/lib/python/script/core.py	2015-07-19 19:23:39 UTC (rev 65663)
@@ -376,8 +376,12 @@
     >>> run_command('g.region', raster='elevation')
     0
 
-    See ``start_command()`` for details about parameters and usage.
+    See :func:`start_command()` for details about parameters and usage.
 
+    ..note::
+        You should ignore the return value of this function unless, you
+        change the default behavior using *errors* parameter.
+
     :param *args: unnamed arguments passed to ``start_command()``
     :param **kwargs: named arguments passed to ``start_command()``
 
@@ -603,7 +607,7 @@
 
     This function does not end the execution of the program.
     The right action after the error is up to the caller.
-    For error handling using the standard mechanism use :func:`fatal`.
+    For error handling using the standard mechanism use :func:`fatal()`.
 
     :param str msg: error message to be displayed
     """
@@ -615,7 +619,7 @@
 
     Raises exception when module global raise_on_error is 'True', abort
     (calls exit) otherwise.
-    Use func:`set_raise_on_error` to set the behavior.
+    Use :func:`set_raise_on_error()` to set the behavior.
 
     :param str msg: error message to be displayed
     """
@@ -988,7 +992,7 @@
     If no 'kwargs' are given then the current region is used. Note
     that this function doesn't modify the current region!
 
-    See also use_temp_region() for alternative method how to define
+    See also :func:`use_temp_region()` for alternative method how to define
     temporary region used for raster-based computation.
 
     :param bool region3d: True to get 3D region
@@ -1517,11 +1521,12 @@
 def legal_name(s):
     """Checks if the string contains only allowed characters.
 
-    This is the Python implementation of G_legal_filename() function.
+    This is the Python implementation of :func:`G_legal_filename()` function.
 
     ..note::
 
-        It is not clear when to use this function.
+        It is not clear when exactly use this function, but it might be
+        useful anyway for checking map names and column names.
     """
     if not s or s[0] == '.':
         warning(_("Illegal filename <%s>. Cannot be 'NULL' or start with " \