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(....)?
Did I miss an important mention about the topic in the manual?
Daehyok Shin (Peter)
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@virgin.net>
On Wed, Apr 23, 2003 at 05:13:37AM +0100, Glynn Clements wrote:
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.
[...]
> 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.
In GRASS 5.1 we have started to use 'doxygen' and to keep the docs
inside the source code (so as close as possible). 'doxygen'
(www.doxygen.org) creates HTML and PDF (and ..) docs from the source
code.
The GRASS 5.1 programmer's manual is generated from the source code
each saturday (http://grass.itc.it/grass51/manuals/).
The next years we'll probably move most of the docs into the source code,
but that's a demanding job (volunteers needed)...
Markus Neteler