doxygen updated (diglib/file.c)

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

lib/vector/diglib/file.c

@@ -1,19 +1,22 @@
+/*!
+   \file diglib/file.c
+
+   \brief Vector library (diglib) - file management
+
+   Lower level functions for reading/writing/manipulating vectors.
+
+   Note: seems that the time is almost the same for both cases: 
+    - reading from file 
+    - load whole file to memory and read from memory
+   
+   (C) 2001-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.
+
+   \author Dave Gerdes, Radim Blazek
+ */
 
-/****************************************************************************
-*
-* MODULE:       Vector library 
-*   	    	
-* AUTHOR(S):    Dave Gerdes, Radim Blazek
-*
-* PURPOSE:      Lower level functions for reading/writing/manipulating vectors.
-*
-* COPYRIGHT:    (C) 2001 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/config.h>
 #include <string.h>
 #include <stdio.h>
@@ -22,32 +25,42 @@
 #include <sys/stat.h>
 #include <grass/gis.h>
 #include <grass/Vect.h>
+#include <grass/glocale.h>
 
-/* 
- *  Note: seems that the time is almost the same for both cases: 
- *        - reading from file 
- *        - load whole file to memory and read from memory
- */
+/*!
+  \brief Get GVFILE position.
 
-/* Get GVFILE position.
- *
- *  Returns: current file position
- */
-off_t dig_ftell(GVFILE * file)
+  \param file pointer to GVFILE structure
+
+  \return current file position
+*/
+off_t dig_ftell(GVFILE *file)
 {
-    if (file->loaded)		/* using memory */
+    if (file->loaded) /* using memory */
 	return (file->current - file->start);
 
     return (G_ftell(file->file));
 }
 
-/* Set GVFILE position.
- *
- *  Returns: 0 OK, -1 error
- */
+/*!
+  \brief Set GVFILE position.
+ 
+  Start positions:
+  
+   - SEEK_SET (start)
+   - SEEK_CUR (current position)
+   - SEEK_END (end)
+  
+  \param file pointer to GVFILE structure
+  \param offset offset position
+  \param whence start position
+
+  \return 0 OK
+  \return -1 error
+*/
 int dig_fseek(GVFILE * file, off_t offset, int whence)
 {
-    if (file->loaded) {		/* using memory */
+    if (file->loaded) {	 /* using memory */
 	switch (whence) {
 	case SEEK_SET:
 	    file->current = file->start + offset;
@@ -67,13 +80,14 @@ int dig_fseek(GVFILE * file, off_t offset, int whence)
     return  0;
 }
 
-/* Rewind  GVFILE position.
- *
- *  Returns: nothing
- */
+/*!
+  \brief Rewind GVFILE position.
+ 
+  \param file pointer to GVFILE structure
+*/
 void dig_rewind(GVFILE * file)
 {
-    if (file->loaded) {		/* using memory */
+    if (file->loaded) {	/* using memory */
 	file->current = file->start;
     }
     else {
@@ -81,13 +95,16 @@ void dig_rewind(GVFILE * file)
     }
 }
 
-/* Flush GVFILE.
- *
- *  Returns: nothing
- */
+/*!
+  \brief Flush GVFILE.
+ 
+  \param file pointer to GVFILE structure
+
+  \return 0
+*/
 int dig_fflush(GVFILE * file)
 {
-    if (file->loaded) {		/* using memory */
+    if (file->loaded) {	/* using memory */
 	return 0;
     }
     else {
@@ -95,17 +112,23 @@ int dig_fflush(GVFILE * file)
     }
 }
 
-/* Read GVFILE.
- *
- *  Returns: number of read members
+/*!
+  \brief Read GVFILE.
+ 
+  \param[out] ptr data buffer
+  \param size buffer size
+  \param nmemb number of members
+  \param file pointer to GVFILE structure
+
+  \return number of read members
  */
-size_t dig_fread(void *ptr, size_t size, size_t nmemb, GVFILE * file)
+size_t dig_fread(void *ptr, size_t size, size_t nmemb, GVFILE *file)
 {
     long tot;
     size_t cnt;
 
-    if (file->loaded) {		/* using memory */
-	if (file->current >= file->end) {	/* EOF */
+    if (file->loaded) {	/* using memory */
+	if (file->current >= file->end) { /* EOF */
 	    return 0;
 	}
 	tot = size * nmemb;
@@ -121,24 +144,31 @@ size_t dig_fread(void *ptr, size_t size, size_t nmemb, GVFILE * file)
     return (fread(ptr, size, nmemb, file->file));
 }
 
-/* Write GVFILE.
- *
- *  Returns: number of items written
+/*!
+  \brief Write GVFILE.
+
+  \param ptr data buffer
+  \param size buffer size
+  \param nmemb number of members
+  \param[out] file pointer to GVFILE structure
+
+  \return number of items written
  */
-size_t dig_fwrite(void *ptr, size_t size, size_t nmemb, GVFILE * file)
+size_t dig_fwrite(void *ptr, size_t size, size_t nmemb, GVFILE *file)
 {
-    if (file->loaded) {		/* using memory */
-	G_fatal_error("Writing to file loaded to memory not supported");
+    if (file->loaded) {	/* using memory */
+	G_fatal_error(_("Writing to file loaded to memory not supported"));
     }
 
     return fwrite(ptr, size, nmemb, file->file);
 }
 
-/* Init GVFILE.
- *
- *  Returns: nothing
- */
-void dig_file_init(GVFILE * file)
+/*!
+  \brief Initialize GVFILE.
+  
+  \param[out] file pointer to GVFILE structure
+*/
+void dig_file_init(GVFILE *file)
 {
     file->file = NULL;
     file->start = NULL;
@@ -149,11 +179,17 @@ void dig_file_init(GVFILE * file)
     file->loaded = 0;
 }
 
-/* Load opened GVFILE to memory.
- *  Warning: position in file is set to the beginning.
- *
- *  Returns: 1 loaded, 0, not loaded, -1 Error
- */
+/*!
+  \brief Load opened GVFILE to memory.
+ 
+  Warning: position in file is set to the beginning.
+ 
+  \param file pointer to GVFILE structure
+
+  \return 1 loaded
+  \return 0 not loaded
+  \return -1 error
+*/
 int dig_file_load(GVFILE * file)
 {
     int ret, mode, load;
@@ -164,7 +200,7 @@ int dig_file_load(GVFILE * file)
     G_debug(2, "dig_file_load ()");
 
     if (file->file == NULL) {
-	G_warning("Cannot load file to memory, file not open.");
+	G_warning(_("Unable to load file to memory, file not open"));
 	return -1;
     }
 
@@ -179,7 +215,7 @@ int dig_file_load(GVFILE * file)
 	else if (G_strcasecmp(cmode, "AUTO") == 0)
 	    mode = GV_MEMORY_AUTO;
 	else
-	    G_warning("Vector memory mode not supported, using 'AUTO'");
+	    G_warning(_("Vector memory mode not supported, using 'AUTO'"));
     }
     G_debug(2, "  requested mode = %d", mode);
 
@@ -187,7 +223,7 @@ int dig_file_load(GVFILE * file)
     fstat(fileno(file->file), &sbuf);
     size = sbuf.st_size;
 
-    G_debug(2, "  size = %ld", size);
+    G_debug(2, "  size = %lu", (long unsigned int) size);
 
     /* Decide if the file should be loaded */
     /* TODO: I don't know how to get size of free memory (portability) to decide if load or not for auto */
@@ -228,10 +264,11 @@ int dig_file_load(GVFILE * file)
     return 0;
 }
 
-/* Free GVFILE.
- *
- *  Returns: nothing
- */
+/*!
+  \brief Free GVFILE.
+
+  \param file pointer to GVFILE structure
+*/
 void dig_file_free(GVFILE * file)
 {
     if (file->loaded) {