r.li: change calculateIndex interface to respect the way how it is used in r.li modules

 * r.li modules were returning 1 as return code on success
 * now r.diversity works
 * alternative, more invasive change would be to leave calculateIndex interface as is a change all calls (it's not clear what was the original intention)
 * add r.le paper to r.li references
 * more explanation for developer things in user documentation


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

raster/r.li/r.li.daemon/daemon.c

@@ -177,7 +177,9 @@ int calculateIndex(char *file, rli_func *f,
 	G_done_msg("Result written to text file <%s>", out);
     }
 
-    return 1;
+    /* This is only return in this function, so the documented 1 is
+       actually never returned. */
+    return 0;
 }
 
 

raster/r.li/r.li.daemon/daemon.h

@@ -137,8 +137,14 @@ typedef int rli_func(int fd, char **par, struct area_entry *ad, double *result);
  * \param file name of setup file
  * \param f the function that defines the index
  * \param raster the raster file to analyze
- * \return 0 error occurs in calculating index
- * \return 1  otherwise
+ * \return 1 error occurs in calculating index
+ * \return 0 otherwise
+ *
+ * \note
+ * Unlike other function in r.li, this function returns return code
+ * usable as process return code rather than using true/false (1/0)
+ * idiom for success/failure. The interface was designed to accommodate
+ * common usage of this function in r.li modules.
  */
 
 int calculateIndex(char *file, rli_func *f,

raster/r.li/r.li.daemon/r.li.daemon.html

@@ -1,6 +1,17 @@
 <!-- meta page description: Support for landscape index calculations on raster -->
 <h2>DESCRIPTION</h2>
 
+This documentation is focused on scientists and developers who wants to
+implement a new landscape index computation. Refer to the
+<a href="r.li.html">r.li</a> modules overview and
+<a href="g.gui.rlisetup.html">g.gui.rlisetup</a> module for user-focused
+documentation.
+
+<p>
+<!--
+TODO: make this clear and rename daemon to library since it is library and not a daemon
+TODO: here can be just a really short intro and instructions how to get doxygen doc
+-->
 <em>r.li.daemon</em> provides support for landscape index calculations on raster
 maps. It hides the management of areas, defined using <a href="g.gui.rlisetup.html">g.gui.rlisetup</a>
 command. It is not used like a standalone program, but its functions are 
@@ -16,21 +27,23 @@ To write a new index only two steps are needed:
 	<li>
 	Define a function and insert its declaration on file <b>index.h</b> in <em>r.li.daemon</em>
 	folder, which contains all index declarations. This function must be of this kind:
-	<br><div class="code"><pre>
+	<div class="code"><pre>
         int index(int fd, char ** par, area_des ad, double * result)
-	</pre></div><br>
+	</pre></div>
 	where: <ul>
 			<li><i>fd</i> is the raster map descriptor
 			<li><i>par</i> is a matrix for special parameter (like argv in main)
 			<li><i>ad</i> is the area descriptor 
 			<li><i>result</i> is where to put the index calculation result
 		</ul>
-	This function has to return 1 on success and 0 otherwise. <br><br>
+	This function has to return 1 on success and 0 otherwise.
+    This function type is defined using typedef named <code>rli_func</code>.
 	<li>
 	Create a main for command line arguments parsing, and call the function
-	<br><div class="code"><pre>
-        int calculateIndex(char * file, int f(int, char** area_des, double *), char **parameters, char *raster, char *output);
-	</pre></div><br>
+	<div class="code"><pre>
+        int calculateIndex(char *file, rli_func *f,
+                           char **parameters, char *raster, char *output);
+	</pre></div>
 	from the <i>r.li</i> library, for starting raster analysis.<br>
 	It follows the meaning of parameters:
 	<ul>
@@ -43,6 +56,10 @@ To write a new index only two steps are needed:
 </ol>
 Compile it using a changed Makefile based on the file for <em>r.li.patchdensity</em>.
 
+<p>
+Refer to the <i>r.li</i> library documentation in the source code and
+implementation of <i>r.li</i> modules for details and examples.
+
 <h2>NOTES</h2>
 
 Using GRASS library function to access raster rows can slow down moving windows 

raster/r.li/r.li.html

@@ -170,16 +170,24 @@ architecture and the functions are clearly separated, thus allowing an
 easy expandability. Every index is defined separately, placed in a
 directory along with its Makefile for compiling it and a file
 <module_name>.html which describes the index including a simple
-example of use.
+example of use. See <a href="r.li.daemon.html">r.li.daemon</a>
+for more information about development.
 
 
 <h2>REFERENCES</h2>
 
+<ul>
+<li>
 McGarigal, K., and B. J. Marks. 1995. FRAGSTATS: spatial pattern
 analysis program for quantifying landscape structure. USDA For. Serv.
 Gen. Tech. Rep. PNW-351
  (<a href="http://www.fs.fed.us/pnw/pubs/gtr_351.pdf">PDF</a>).
 
+<li>
+Baker, W.L. and Y. Cai. 1992. The r.le programs for multiscale analysis of
+landscape structure using the GRASS geographical information system.
+Landscape Ecology 7(4):291-302.
+</ul>
 
 <h2>AUTHORS</h2>