[GRASS-SVN] r56795 - grass/branches/releasebranch_6_4/lib/python

[svn_grass at osgeo.org]

Author: hamish
Date: 2013-06-19 04:29:55 -0700 (Wed, 19 Jun 2013)
New Revision: 56795

Modified:
   grass/branches/releasebranch_6_4/lib/python/core.py
Log:
add usage example for find_program, note that the exe needs to return with a non-zero exit code (merge from devbr6)

Modified: grass/branches/releasebranch_6_4/lib/python/core.py
===================================================================
--- grass/branches/releasebranch_6_4/lib/python/core.py	2013-06-19 11:28:42 UTC (rev 56794)
+++ grass/branches/releasebranch_6_4/lib/python/core.py	2013-06-19 11:29:55 UTC (rev 56795)
@@ -971,11 +971,25 @@
 
 def find_program(pgm, args = []):
     """!Attempt to run a program, with optional arguments. 
+    You must call the program in a way that will return a successful
+    exit code. For GRASS modules this means you need to pass it some
+    valid CLI option, like "--help". For other programs a common
+    valid do-little option is "--version".
+  
+    Example:
 
+    @code
+    >>> grass.find_program('r.sun', ['help'])
+    True
+    >>> grass.find_program('gdalwarp', ['--version'])
+    True
+    @endcode
+
     @param pgm program name
     @param args list of arguments
 
     @return False if the attempt failed due to a missing executable
+            or non-zero return code
     @return True otherwise
     """
     nuldev = file(os.devnull, 'w+')