From: Andy Spencer <andy753421@gmail.com>
Date: Mon, 8 Feb 2010 22:29:22 +0000 (+0000)
Subject: Document GisData
X-Git-Tag: v0.4~60
X-Git-Url: http://pileus.org/git/?p=grits;a=commitdiff_plain;h=25e9fd85ed1dbf7e4695a9cac456eee73362f6a1

Document GisData
---

diff --git a/src/data/gis-data.c b/src/data/gis-data.c
index d3e5b9b..1126825 100644
--- a/src/data/gis-data.c
+++ b/src/data/gis-data.c
@@ -15,6 +15,15 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * SECTION:gis-data
+ * @short_description: Miscellaneous utilities for data access
+ * @include: glib/gstdio.h
+ *
+ * Various support routines for data access,
+ * these are mostly related to disk caching.
+ */
+
 #include <config.h>
 #include <stdio.h>
 #include <glib.h>
@@ -22,7 +31,13 @@
 #include "gis-data.h"
 
 /**
+ * fopen_p:
+ * @path: the path to the file to be opened.
+ * @mode: mode to open the file, see <function>fopen</function> for details
+ *
  * Open a file, creating parent directories if needed
+ *
+ * Returns: the opened file descriptor
  */
 FILE *fopen_p(const gchar *path, const gchar *mode)
 {
diff --git a/src/data/gis-data.h b/src/data/gis-data.h
index 7c8a728..671280d 100644
--- a/src/data/gis-data.h
+++ b/src/data/gis-data.h
@@ -21,25 +21,34 @@
 #include <glib.h>
 
 /**
- * Various ways to cach a file
+ * GisCacheType:
+ * @GIS_LOCAL:   Only return local files (for offline mode)
+ * @GIS_ONCE:    Download the file only if it does not exist
+ * @GIS_UPDATE:  Update the file to be like the server
+ * @GIS_REFRESH: Delete the existing file and fetch a new copy
+ *
+ * Various methods for caching data
  */
 typedef enum {
-	GIS_LOCAL,   // Only return local files (for offline mode)
-	GIS_ONCE,    // Download the file only if it does not exist
-	GIS_UPDATE,  // Update the file to be like the server
-	GIS_REFRESH, // Delete the existing file and fetch a new copy
+	GIS_LOCAL,
+	GIS_ONCE,
+	GIS_UPDATE,
+	GIS_REFRESH,
 } GisCacheType;
 
 /**
+ * GisChunkCallback:
+ * @file:      path to the file which is being fetched
+ * @cur:       current offset in the file
+ * @total:     total size of the file
+ * @user_data: the user_data argument passed to the function
+ *
  * Function called when part of a file is fetched
  * Used for updating progress bars, etc
  */
 typedef void (*GisChunkCallback)(gchar *file, goffset cur,
 		goffset total, gpointer user_data);
 
-/**
- * Open a file and create the parent directory if necessasairy
- */
 FILE *fopen_p(const gchar *path, const gchar *mode);
 
 #endif