db ogr driver: initial doxygen strings added

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

db/drivers/ogr/cursor.c

@@ -4,10 +4,11 @@
 * MODULE:       OGR driver 
 *   	    	
 * AUTHOR(S):    Radim Blazek
+*               Some updates by Martin Landa <landa.martin gmail.com>
 *
 * PURPOSE:      DB driver for OGR sources     
 *
-* COPYRIGHT:    (C) 2004 by the GRASS Development Team
+* COPYRIGHT:    (C) 2004-2009 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
@@ -15,34 +16,50 @@
 *
 *****************************************************************************/
 #include <stdio.h>
+
 #include <grass/gis.h>
 #include <grass/dbmi.h>
+#include <grass/glocale.h>
+
 #include "ogr_api.h"
 #include "globals.h"
 #include "proto.h"
 
+/*!
+  \brief Close cursor
+
+  \param dbc pointer to dbCursor to be closed
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
+*/
 int db__driver_close_cursor(dbCursor * dbc)
 {
     cursor *c;
 
     G_debug(3, "db_driver_close_cursor()");
-
+    
     init_error();
 
     /* get my cursor via the dbc token */
     c = (cursor *) db_find_token(db_get_cursor_token(dbc));
     if (c == NULL)
 	return DB_FAILED;
-
+    
     /* free_cursor(cursor) */
     free_cursor(c);
-
+    
     G_debug(3, "Cursor closed");
 
     return DB_OK;
 }
 
+/*!
+  \brief Allocate cursor
 
+  \return pointer to cursor structure
+  \return NULL on error
+*/
 cursor *alloc_cursor()
 {
     cursor *c;
@@ -50,14 +67,14 @@ cursor *alloc_cursor()
     /* allocate the cursor */
     c = (cursor *) db_malloc(sizeof(cursor));
     if (c == NULL) {
-	append_error("Cannot allocate cursor.");
+	append_error(_("Unable to allocate cursor"));
 	return NULL;
     }
 
     /* tokenize it */
     c->token = db_new_token(c);
     if (c->token < 0) {
-	append_error("Cannot ad new token.");
+	append_error(_("Unable to add new token"));
 	return NULL;
     }
 
@@ -66,6 +83,11 @@ cursor *alloc_cursor()
     return c;
 }
 
+/*!
+  \brief Free cursor structure (destroy OGR feature and release OGR layer)
+
+  \param c pointer to cursor
+*/
 void free_cursor(cursor * c)
 {
     if (c->hFeature)

db/drivers/ogr/db.c

@@ -4,24 +4,37 @@
 * MODULE:       OGR driver 
 *   	    	
 * AUTHOR(S):    Radim Blazek
+*               Some updates by Martin Landa <landa.martin gmail.com>
 *
 * PURPOSE:      DB driver for OGR sources     
 *
-* COPYRIGHT:    (C) 2004 by the GRASS Development Team
+* COPYRIGHT:    (C) 2004-2009 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.
 *
 *****************************************************************************/
+
 #include <stdlib.h>
 #include <string.h>
+
 #include <grass/gis.h>
 #include <grass/dbmi.h>
+#include <grass/glocale.h>
+
 #include "ogr_api.h"
 #include "globals.h"
 #include "proto.h"
 
+/*!
+  \brief Open database (OGR datasource)
+
+  \param handle pointer to dbHandle (db name and schema)
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
+*/
 int db__driver_open_database(dbHandle * handle)
 {
     const char *name;
@@ -42,7 +55,7 @@ int db__driver_open_database(dbHandle * handle)
     hDs = OGROpen(name, FALSE, NULL);
 
     if (hDs == NULL) {
-	append_error("Cannot open OGR data source");
+	append_error(_("Unable to open OGR data source"));
 	report_error();
 	return DB_FAILED;
     }
@@ -52,6 +65,12 @@ int db__driver_open_database(dbHandle * handle)
     return DB_OK;
 }
 
+/*!
+  \brief Close open database
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
+*/
 int db__driver_close_database()
 {
     G_debug(3, "db_driver_close_database()");

db/drivers/ogr/describe.c

@@ -4,10 +4,11 @@
 * MODULE:       OGR driver 
 *   	    	
 * AUTHOR(S):    Radim Blazek
+*               Some updates by Martin Landa <landa.martin gmail.com>
 *
 * PURPOSE:      DB driver for OGR sources     
 *
-* COPYRIGHT:    (C) 2004 by the GRASS Development Team
+* COPYRIGHT:    (C) 2004-2009 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
@@ -24,15 +25,25 @@
 #include "globals.h"
 #include "proto.h"
 
+/*!
+  \brief Describe table using driver
+
+  \param table_name table name (as dbString)
+  \param table[out] pointer to dbTable
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
+*/
 int db__driver_describe_table(dbString * table_name, dbTable ** table)
 {
     int i, nlayers;
     OGRLayerH hLayer = NULL;
     OGRFeatureDefnH hFeatureDefn;
 
-    /* Find data source */
+    /* get number of OGR layers in the datasource */
     nlayers = OGR_DS_GetLayerCount(hDs);
 
+    /* find OGR layer */
     for (i = 0; i < nlayers; i++) {
 	hLayer = OGR_DS_GetLayer(hDs, i);
 	hFeatureDefn = OGR_L_GetLayerDefn(hLayer);
@@ -45,7 +56,7 @@ int db__driver_describe_table(dbString * table_name, dbTable ** table)
     }
 
     if (hLayer == NULL) {
-	append_error("Table '%s' does not exist\n",
+	append_error(_("OGR layer <%s> does not exist\n"),
 		     db_get_string(table_name));
 	report_error();
 	return DB_FAILED;
@@ -53,7 +64,7 @@ int db__driver_describe_table(dbString * table_name, dbTable ** table)
 
     G_debug(3, "->>");
     if (describe_table(hLayer, table, NULL) == DB_FAILED) {
-	append_error("Cannot describe table\n");
+	append_error(_("Unable to describe table\n"));
 	report_error();
 	return DB_FAILED;
     }
@@ -61,8 +72,15 @@ int db__driver_describe_table(dbString * table_name, dbTable ** table)
     return DB_OK;
 }
 
-/* describe table, if c is not NULL cur->cols and cur->ncols is also set 
- * cursor may be null
+/*!
+  \brief Describe table
+
+  If c is not NULL cur->cols and cur->ncols is also set 
+  cursor may be null
+
+  \param hLayer OGR layer
+  \param[put] table pointer to dbTable
+  \param c pointer to cursor
  */
 int describe_table(OGRLayerH hLayer, dbTable **table, cursor *c)
 {

db/drivers/ogr/driver.c

@@ -4,27 +4,43 @@
 * MODULE:       OGR driver 
 *   	    	
 * AUTHOR(S):    Radim Blazek
+*               Some updates by Martin Landa <landa.martin gmail.com>
 *
 * PURPOSE:      DB driver for OGR sources     
 *
-* COPYRIGHT:    (C) 2004 by the GRASS Development Team
+* COPYRIGHT:    (C) 2004-2009 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.
 *
 *****************************************************************************/
+
 #include <grass/dbmi.h>
+
 #include "ogr_api.h"
 #include "globals.h"
 #include "proto.h"
 
+/*!
+  \brief Initialize driver
+
+  \param argc number of arguments
+  \param argv array of arguments
+
+  \return DB_OK on success
+*/
 int db__driver_init(int argc, char *argv[])
 {
     init_error();
     return DB_OK;
 }
 
+/*!
+  \brief Finish driver
+
+  \return DB_OK
+*/
 int db__driver_finish()
 {
     return DB_OK;

db/drivers/ogr/error.c

@@ -4,26 +4,33 @@
 * MODULE:       OGR driver 
 *   	    	
 * AUTHOR(S):    Radim Blazek
+*               Some updates by Martin Landa <landa.martin gmail.com>
 *
 * PURPOSE:      DB driver for OGR sources     
 *
-* COPYRIGHT:    (C) 2004 by the GRASS Development Team
+* COPYRIGHT:    (C) 2004-2009 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.
 *
 *****************************************************************************/
+
 #include <stdlib.h>
 #include <stdio.h>
 #include <stdarg.h>
-#include <grass/dbmi.h>
+
 #include <grass/gis.h>
+#include <grass/dbmi.h>
+#include <grass/glocale.h>
+
 #include "ogr_api.h"
 #include "globals.h"
 #include "proto.h"
 
-/* init error message */
+/*!
+  \brief Init error message
+*/
 void init_error(void)
 {
     if (!errMsg) {
@@ -31,10 +38,14 @@ void init_error(void)
 	db_init_string(errMsg);
     }
 
-    db_set_string(errMsg, "DBMI-OGR driver error:\n");
+    db_set_string(errMsg, _("DBMI-OGR driver error:\n"));
 }
 
-/* append error message */
+/*!
+  \brief Append error message
+
+  \param fmt formatted string
+*/
 void append_error(const char *fmt, ...)
 {
     FILE *fp = NULL;
@@ -56,6 +67,9 @@ void append_error(const char *fmt, ...)
     va_end(ap);
 }
 
+/*!
+  \brief Report errors
+*/
 void report_error(void)
 {
     db_append_string(errMsg, "\n");

db/drivers/ogr/fetch.c

@@ -4,10 +4,11 @@
 * MODULE:       OGR driver 
 *   	    	
 * AUTHOR(S):    Radim Blazek
+*               Some updates by Martin Landa <landa.martin gmail.com>
 *
 * PURPOSE:      DB driver for OGR sources     
 *
-* COPYRIGHT:    (C) 2004 by the GRASS Development Team
+* COPYRIGHT:    (C) 2004-2009 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
@@ -16,20 +17,32 @@
 *****************************************************************************/
 #include <stdlib.h>
 #include <string.h>
+
 #include <grass/gis.h>
 #include <grass/dbmi.h>
+#include <grass/glocale.h>
+
 #include "ogr_api.h"
 #include "globals.h"
 #include "proto.h"
-#include <grass/glocale.h>
 
+/*!
+  \brief Fetch record
+
+  \param cn pointer to dbCursor
+  \param position position indicator (DB_NEXT, DB_FIRST, DB_LAST, etc)
+  \param[out] more 0 for no record fetched otherwise 1
+
+  \return DB_OK on success
+  \return DB_FAILED on error
+*/
 int db__driver_fetch(dbCursor * cn, int position, int *more)
 {
     cursor *c;
     dbToken token;
     dbTable *table;
     int i, col;
-
+    
     G_debug(3, "db_driver_fetch()");
 
     /* get cursor token */
@@ -37,7 +50,7 @@ int db__driver_fetch(dbCursor * cn, int position, int *more)
 
     /* get the cursor by its token */
     if (!(c = (cursor *) db_find_token(token))) {
-	append_error("Cursor not found");
+	append_error(_("Cursor not found"));
 	report_error();
 	return DB_FAILED;
     }
@@ -53,7 +66,7 @@ int db__driver_fetch(dbCursor * cn, int position, int *more)
     case DB_CURRENT:
 	break;
     case DB_PREVIOUS:
-	append_error("DB_PREVIOUS not supported");
+	append_error(_("DB_PREVIOUS not supported"));
 	report_error();
 	return DB_FAILED;
 	break;
@@ -64,7 +77,7 @@ int db__driver_fetch(dbCursor * cn, int position, int *more)
 	c->hFeature = OGR_L_GetNextFeature(c->hLayer);
 	break;
     case DB_LAST:
-	append_error("DB_LAST not supported");
+	append_error(_("DB_LAST not supported"));
 	report_error();
 	return DB_FAILED;
 	break;
@@ -79,13 +92,12 @@ int db__driver_fetch(dbCursor * cn, int position, int *more)
 
     /* get the data out of the descriptor into the table */
     table = db_get_cursor_table(cn);
-
     col = -1;
     for (i = 0; i < c->ncols; i++) {
 	int ogrType, sqlType;
 	dbColumn *column;
 	dbValue *value;
-
+	
 	if (!(c->cols[i])) {
 	    continue;
 	}			/* unknown type */
@@ -134,6 +146,14 @@ int db__driver_fetch(dbCursor * cn, int position, int *more)
     return DB_OK;
 }
 
+/*
+  \brief Get number of rows (i.e. features) in open cursor
+
+  \param cn pointer to dbCursor
+
+  \return number of rows
+  \return DB_FAILED on error
+*/
 int db__driver_get_num_rows(dbCursor * cn)
 {
     cursor *c;
@@ -146,7 +166,7 @@ int db__driver_get_num_rows(dbCursor * cn)
 
     /* get the cursor by its token */
     if (!(c = (cursor *) db_find_token(token))) {
-	append_error("Cursor not found");
+	append_error(_("Cursor not found"));
 	report_error();
 	return DB_FAILED;
     }

db/drivers/ogr/globals.h

@@ -4,10 +4,11 @@
 * MODULE:       OGR driver 
 *   	    	
 * AUTHOR(S):    Radim Blazek
+*               Some updates by Martin Landa <landa.martin gmail.com>
 *
 * PURPOSE:      DB driver for OGR sources     
 *
-* COPYRIGHT:    (C) 2004 by the GRASS Development Team
+* COPYRIGHT:    (C) 2004-2009 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
@@ -19,11 +20,11 @@
 typedef struct
 {
     dbToken token;
-    OGRLayerH hLayer;		/* results */
+    OGRLayerH hLayer;		/* current OGR layer */
     OGRFeatureH hFeature;	/* current feature */
     int type;			/* type of cursor: SELECT, UPDATE, INSERT */
     int *cols;			/* 1 type is known, 0 type is unknown */
-    int ncols;			/* num columns */
+    int ncols;			/* num columns (without fid column) */
 } cursor;
 
 extern OGRDataSourceH hDs;

db/drivers/ogr/listtab.c

@@ -4,22 +4,36 @@
 * MODULE:       OGR driver 
 *   	    	
 * AUTHOR(S):    Radim Blazek
+*               Some updates by Martin Landa <landa.martin gmail.com>
 *
 * PURPOSE:      DB driver for OGR sources     
 *
-* COPYRIGHT:    (C) 2004 by the GRASS Development Team
+* COPYRIGHT:    (C) 2004-2009 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.
 *
 *****************************************************************************/
+
 #include <grass/gis.h>
 #include <grass/dbmi.h>
+#include <grass/glocale.h>
+
 #include "ogr_api.h"
 #include "globals.h"
 #include "proto.h"
 
+/*!
+  \brief List tables
+
+  \param[out] tlist list of tables
+  \param[out] tcount number of tables
+  \param system list also system tables
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
+*/
 int db__driver_list_tables(dbString ** tlist, int *tcount, int system)
 {
     int i, nlayers;
@@ -37,7 +51,7 @@ int db__driver_list_tables(dbString ** tlist, int *tcount, int system)
     list = db_alloc_string_array(nlayers);
 
     if (list == NULL) {
-	append_error("Cannot db_alloc_string_array()");
+	append_error(_("Unable to db_alloc_string_array()"));
 	report_error();
 	return DB_FAILED;
     }

db/drivers/ogr/main.c

@@ -4,10 +4,11 @@
 * MODULE:       OGR driver 
 *   	    	
 * AUTHOR(S):    Radim Blazek
+*               Some updates by Martin Landa <landa.martin gmail.com>
 *
 * PURPOSE:      DB driver for OGR sources     
 *
-* COPYRIGHT:    (C) 2004 by the GRASS Development Team
+* COPYRIGHT:    (C) 2004-2009 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
@@ -16,7 +17,9 @@
 *****************************************************************************/
 
 #include <stdlib.h>
+
 #include <grass/dbmi.h>
+
 #include "ogr_api.h"
 #include "globals.h"
 #include "dbdriver.h"

db/drivers/ogr/proto.h

@@ -4,20 +4,17 @@
 * MODULE:       OGR driver 
 *   	    	
 * AUTHOR(S):    Radim Blazek
+*               Some updates by Martin Landa <landa.martin gmail.com>
 *
 * PURPOSE:      DB driver for OGR sources     
 *
-* COPYRIGHT:    (C) 2004 by the GRASS Development Team
+* COPYRIGHT:    (C) 2004-2009 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.
 *
 *****************************************************************************/
-/* error.c */
-void init_error(void);
-void append_error(const char *fmt, ...);
-void report_error(void);
 
 /* cursor.c */
 cursor *alloc_cursor();
@@ -25,3 +22,8 @@ void free_cursor(cursor *);
 
 /* describe.c */
 int describe_table(OGRLayerH, dbTable **, cursor *);
+
+/* error.c */
+void init_error(void);
+void append_error(const char *, ...);
+void report_error(void);

db/drivers/ogr/select.c

@@ -4,22 +4,36 @@
 * MODULE:       OGR driver 
 *   	    	
 * AUTHOR(S):    Radim Blazek
+*               Some updates by Martin Landa <landa.martin gmail.com>
 *
 * PURPOSE:      DB driver for OGR sources     
 *
-* COPYRIGHT:    (C) 2004 by the GRASS Development Team
+* COPYRIGHT:    (C) 2004-2009 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.
 *
 *****************************************************************************/
+
 #include <grass/gis.h>
 #include <grass/dbmi.h>
+#include <grass/glocale.h>
+
 #include "ogr_api.h"
 #include "globals.h"
 #include "proto.h"
 
+/*!
+  \brief Open select cursor
+
+  \param sel select statement (given as dbString)
+  \param[out] dbc pointer to dbCursor
+  \param mode open mode
+
+  \return DB_OK on success
+  \return DB_FAILED on failure
+*/
 int db__driver_open_select_cursor(dbString * sel, dbCursor * dbc, int mode)
 {
     cursor *c;
@@ -38,7 +52,7 @@ int db__driver_open_select_cursor(dbString * sel, dbCursor * dbc, int mode)
     c->hLayer = OGR_DS_ExecuteSQL(hDs, db_get_string(sel), NULL, NULL);
 
     if (c->hLayer == NULL) {
-	append_error("Cannot select: \n");
+	append_error(_("Unable to select: \n"));
 	append_error(db_get_string(sel));
 	append_error("\n");
 	report_error();
@@ -46,7 +60,7 @@ int db__driver_open_select_cursor(dbString * sel, dbCursor * dbc, int mode)
     }
 
     if (describe_table(c->hLayer, &table, c) == DB_FAILED) {
-	append_error("Cannot describe table\n");
+	append_error(_("Unable to describe table\n"));
 	report_error();
 	OGR_DS_ReleaseResultSet(hDs, c->hLayer);
 	return DB_FAILED;