grass
grass copied to clipboard
OSGeo
man: Improve segment library documentation, provide examples
This PR adds two examples into doc/examples which can be compiled as GRASS modules and executed. It adds 3 new sections to the library dox file: about general use with raster, about use with list of rasters (includes portions of one of the examples, so the code is only at one place), and a complete example (here including whole files). Finally, it modifies documentation for two functions.
Besides asking for general review of best practices in using this library, I'm asking these two questions:
- Is the remark about value initialization correct? (I don't really see a point in using calloc instead of malloc there considering that the non-memory case does initialize with zeros.)
- What about the precondition for
Segment_get_row()? DoesSegment_get()need the same one?Segment_flush()description suggests that only writing to disk andSegment_get_row()need that andSegment_get_row()does not call any page function if that has any influence.
This PR adds two examples into
doc/exampleswhich can be compiled as GRASS modules and executed. It adds 3 new sections to the library dox file: about general use with raster, about use with list of rasters (includes portions of one of the examples, so the code is only at one place), and a complete example (here including whole files). Finally, it modifies documentation for two functions.
Please use standard C style in sample code. Maybe documentation does not need to be that long? avoid tl;dr
Besides asking for general review of best practices in using this library, I'm asking these two questions:
* Is the remark about value initialization correct? (I don't really see a point in using calloc instead of malloc there considering that the non-memory case does initialize with zeros.)
See "man calloc". malloc does not initialize the memory while calloc does.
* What about the precondition for `Segment_get_row()`? Does `Segment_get()` need the same one?
No.
Segment_flush()description suggests that only writing to disk andSegment_get_row()need that andSegment_get_row()does not call any page function if that has any influence.
Yes, that's the reason: Segment_get_row() bypasses the internal cache and reads directly from the temporary file.
Considering examples on how to use the segment library, it is IMHO sufficient to mention current working modules like r.cost, r.walk, r.watershed, r.stream.extract.
Jumping into this discussion a bit late, so just two short comments:
-
I think we definitely need enhanced and detailed documentation of the C-code. @metzm, today you are probably the only one to really know the nitty-gritty stuff in this library, so for future sustainability (and possibly attracting the rare C-developer out there), good doc seems a must to me.
-
At this stage, I haven't had the chance to delve into the doc enough to understand whether new (simple) examples are needed. They have the advantage of focusing on the features documented, thus avoiding distraction through other unrelated parts of code. They have the disadvantage of having to be updated when the library changes. Actual production modules obviously provide more motivation to keep them up to date.
I don't think this has been done as such in the code doc, yet, but maybe we could just add specific references to the existing production modules directly into the doc ?
Note to myself: It seems that it worth explicitly noting that functions such as Segment_get() don't do bounds check for row and col (and thus crash will occur rather than an error message).
