[GRASSLIST:6113] Re: Return values in GRASS API?

[Glynn Clements]

Shin, Daehyok wrote:

> While reading the programmer's manual for GRASS 5.x,
> I had a difficulty to find the exact meaning of the returned value from each
> function.
> 
> For instance, what is the meaning of the integer value returned from
> int G_insert_null_values(....)?

Looking at the source code (src/libes/gis/null_val.c) indicates that
the return value is always 1, and so can be ignored.

G_insert_null_values() is just a wrapper around EmbedGivenNulls(), but
with the last two arguments swapped. The comment for EmbedGivenNulls()
says:

* PURPOSE: 	To insert null values into a map. Needs more.....
* INPUT VARS:	cell	    =>	??
*   	    	nulls	    =>	??
*   	    	map_type    =>	type of raster - CELL, FCELL, DCELL
*   	    	ncols	    =>	??
* RETURN VAL:	??

The "??" indicates that whoever wrote the comment didn't know the
meaning of either the return value or most of the arguments. This is
quite common; there are large parts of GRASS which nobody understands
fully (or, in some cases, even partially).

> Did I miss an important mention about the topic in the manual?

Probably not; the programmer's manual is far from complete.

More generally, don't believe what you read in the manual. If someone
changes the code, most of the time they won't bother to update the
manual.

The programmer's manual can be useful to get a general overview, but
if you need a definite answer to a specific question, look at the
source code.

Anything beginning with G_ should be in src/libes/gis; similarly R_ ->
.../raster, D_ -> display, V_ -> vask. The rest of the stuff is less
organised.

-- 
Glynn Clements <glynn.clements at virgin.net>