[GRASS-dev] Programming manual updated: gislib

GRASS GIS GRASS GIS developer
1

Hi all,

I’ve updated the programming manual (r58037), namely Command line parsing documentation in gislib.

I added some important things which were missing such as standard options. I changed some wording such as ‘parser routines’ which really scares me. I also changed the description of API in the way that it is object oriented as opposed to listing functions and structures separately.

I encourage every body to contribute to programming manual because it is crucial for attracting new developers. Well documented API can be more important than the quality of API itself.

Best,
Vaclav

== Details ==

The next step could be to move some details from API description to particular functions and structures and leave in the dox files only the main things combined with examples.

I haven’t touched the Complete Structure Members Table and Description of Complex Structure Members sections which requires another round of consideration.

Feel free to continue in my effort, correct English grammar or improve the documentation itself, e.g. with more current example.

You can compile the programming manual using
make htmldox
and than you can open a file
html/index.html

MarkusN, please, update the online version.

== Links ==

The old link is:

http://grass.osgeo.org/programming7/gislib.html#Command_Line_Parsing

New links:
http://grass.osgeo.org/programming7/gislib_cmdline_parsing.html

http://grass.osgeo.org/programming7/gislib.html

Related source codes:
http://grass.osgeo.org/programming7/parser__standard__options_8c_source.html

http://grass.osgeo.org/programming7/parser__standard__options_8c.html

http://grass.osgeo.org/programming7/gis_8h.html

Change sets:
https://trac.osgeo.org/grass/changeset/58036 (mv)

https://trac.osgeo.org/grass/changeset/58037 (chnages)

Related GRASS Wiki pages:
http://grasswiki.osgeo.org/wiki/Module_command_line_parser

http://grasswiki.osgeo.org/wiki/GRASS_Programming_Howto

http://grasswiki.osgeo.org/wiki/GRASS_Python_Scripting_Library

(some of them are trying to substitute programming manual)

2

I’ve added even more updates. Now the things from gis.h such as Option structure or STD_OPT enum are displayed in doxygen docs with member descriptions. I wrote something but mostly it was just adding doxygen enabled comments and adding links on places which cannot be recognized by doxygen.

I was afraid that I will break some special parsing somewhere so I didn’t removed /**/ comment at the beginning of enums. My GRASS compiles and runs, so probably it is ok.

Additionally, I tried to disable as much test code as possible, so the documentation should be cleaner now. Remaining things are usually Python classes or functions because I was disabling using file pattern. There is also a pattern for entities, maybe we can introduce some naming convention…

There is also a file ./lib/bitmap/main.c which goes to the docs and I don’t know what’s its purpose.

I also excluded *local_proto.h files which were in the docs sometimes.

Vaclav

r58047: https://trac.osgeo.org/grass/changeset/58048

r58048: https://trac.osgeo.org/grass/changeset/58047

···

On Fri, Oct 18, 2013 at 1:05 AM, Vaclav Petras <wenzeslaus@gmail.com> wrote:

Hi all,

I’ve updated the programming manual (r58037), namely Command line parsing documentation in gislib.

I added some important things which were missing such as standard options. I changed some wording such as ‘parser routines’ which really scares me. I also changed the description of API in the way that it is object oriented as opposed to listing functions and structures separately.

I encourage every body to contribute to programming manual because it is crucial for attracting new developers. Well documented API can be more important than the quality of API itself.

Best,
Vaclav

== Details ==

The next step could be to move some details from API description to particular functions and structures and leave in the dox files only the main things combined with examples.

I haven’t touched the Complete Structure Members Table and Description of Complex Structure Members sections which requires another round of consideration.

Feel free to continue in my effort, correct English grammar or improve the documentation itself, e.g. with more current example.

You can compile the programming manual using
make htmldox
and than you can open a file
html/index.html

MarkusN, please, update the online version.

== Links ==

The old link is:

http://grass.osgeo.org/programming7/gislib.html#Command_Line_Parsing

New links:
http://grass.osgeo.org/programming7/gislib_cmdline_parsing.html

http://grass.osgeo.org/programming7/gislib.html

Related source codes:
http://grass.osgeo.org/programming7/parser__standard__options_8c_source.html

http://grass.osgeo.org/programming7/parser__standard__options_8c.html

http://grass.osgeo.org/programming7/gis_8h.html

Change sets:
https://trac.osgeo.org/grass/changeset/58036 (mv)

https://trac.osgeo.org/grass/changeset/58037 (chnages)

Related GRASS Wiki pages:
http://grasswiki.osgeo.org/wiki/Module_command_line_parser

http://grasswiki.osgeo.org/wiki/GRASS_Programming_Howto

http://grasswiki.osgeo.org/wiki/GRASS_Python_Scripting_Library

(some of them are trying to substitute programming manual)