rasterlib/gdal.c: add doxygen docs

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

lib/raster/gdal.c

@@ -1,3 +1,15 @@
+/*!
+  \file lib/raster/gdal.c
+  
+  \brief Raster Library - Utilization of GDAL library.
+  
+  (C) 2010 by the GRASS Development Team
+  
+  This program is free software under the GNU General Public License
+  (>=v2). Read the file COPYING that comes with GRASS for details.
+  
+  \author Glynn Clements
+*/
 
 #include <stdlib.h>
 #include <string.h>
@@ -99,6 +111,7 @@ static void load_library(void)
 	"libgdal.so",
 # endif
 # ifdef _WIN32
+	"gdal17.dll",
 	"gdal16.dll",
 	"gdal15.dll",
 	"gdal11.dll",
@@ -180,6 +193,11 @@ static void init_gdal(void)
 
 #endif /* GDAL_LINK */
 
+/*!
+  \brief Initialization
+
+  Register all GDAL drivers.
+*/
 void Rast_init_gdal(void)
 {
 #ifdef GDAL_LINK
@@ -194,6 +212,15 @@ void Rast_init_gdal(void)
 #endif
 }
 
+/*!
+  \brief Get GDAL link settings for given raster map
+
+  \param name map name
+  \param mapset name of mapset
+
+  \return pointer to GDAL_link structure
+  \return NULL if link not found
+*/
 struct GDAL_link *Rast_get_gdal_link(const char *name, const char *mapset)
 {
 #ifdef GDAL_LINK
@@ -363,6 +390,15 @@ static void read_gdal_options(void)
     G_free_key_value(key_val);
 }
 
+/*!
+  \brief Create GDAL settings for given raster map
+
+  \param name map name
+  \param map_type map type (CELL, FCELL, DCELL)
+
+  \return pointer to allocated GDAL_link structure
+  \return NULL on error
+*/
 struct GDAL_link *Rast_create_gdal_link(const char *name,
 					RASTER_MAP_TYPE map_type)
 {
@@ -519,6 +555,11 @@ struct GDAL_link *Rast_create_gdal_link(const char *name,
 #endif
 }
 
+/*!
+  \brief Close existing GDAL link
+  
+  \param gdal pointer to GDAL_link to be closed
+*/
 void Rast_close_gdal_link(struct GDAL_link *gdal)
 {
 #ifdef GDAL_LINK
@@ -528,6 +569,14 @@ void Rast_close_gdal_link(struct GDAL_link *gdal)
     G_free(gdal);
 }
 
+/*!
+  \brief Close exising GDAL link and write out data
+
+  \param gdal pointer to GDAL_link to be closed
+
+  \return 1 on success
+  \return -1 on failure
+*/
 int Rast_close_gdal_write_link(struct GDAL_link *gdal)
 {
     int stat = 1;
@@ -559,6 +608,11 @@ int Rast_close_gdal_write_link(struct GDAL_link *gdal)
 }
 
 #ifdef GDAL_LINK
+/*!
+  \brief Input/output function for GDAL links
+
+  See GDAL's RasterIO for details.
+*/
 CPLErr Rast_gdal_raster_IO(GDALRasterBandH band, GDALRWFlag rw_flag,
 			   int x_off, int y_off, int x_size, int y_size,
 			   void *buffer, int buf_x_size, int buf_y_size,