From acac053ecfb840a9697d5d9d7e600f1f1ba0ab00 Mon Sep 17 00:00:00 2001
From: Andy Spencer <andy753421@gmail.com>
Date: Mon, 8 Feb 2010 22:29:31 +0000
Subject: [PATCH] Document GisHttp

---
 src/data/gis-http.c | 39 +++++++++++++++++++++++++++++++++++++++
 src/data/gis-http.h | 16 ----------------
 2 files changed, 39 insertions(+), 16 deletions(-)

diff --git a/src/data/gis-http.c b/src/data/gis-http.c
index e64d5ba..fb742c7 100644
--- a/src/data/gis-http.c
+++ b/src/data/gis-http.c
@@ -15,6 +15,16 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * SECTION:gis-http
+ * @short_description: Hyper Text Transfer Protocol
+ *
+ * #GisHttp is a small wrapper around libsoup to provide data access using the
+ * Hyper Text Transfer Protocol. Each #GisHttp should be associated with a
+ * particular server or dataset, all the files downloaded for this dataset will
+ * be cached together in $HOME.cache/libgis/
+ */
+
 #include <config.h>
 #include <glib.h>
 #include <glib/gstdio.h>
@@ -22,6 +32,15 @@
 
 #include "gis-http.h"
 
+/**
+ * gis_http_new:
+ * @prefix: The prefix in the cache to store the downloaded files.
+ *          For example: * "/nexrad/level2/".
+ *
+ * Create a new #GisHttp for the given prefix
+ *
+ * Returns: the new #GisHttp
+ */
 GisHttp *gis_http_new(const gchar *prefix)
 {
 	g_debug("GisHttp: new - %s", prefix);
@@ -32,6 +51,12 @@ GisHttp *gis_http_new(const gchar *prefix)
 	return http;
 }
 
+/**
+ * gis_http_free:
+ * @http: the #GisHttp to free
+ *
+ * Frees resources used by @http and cancels any pending requests.
+ */
 void gis_http_free(GisHttp *http)
 {
 	g_debug("GisHttp: free - %s", http->prefix);
@@ -74,6 +99,20 @@ static void _chunk_cb(SoupMessage *message, SoupBuffer *chunk, gpointer _info)
 	}
 }
 
+/**
+ * gis_http_fetch:
+ * @http:      the #GisHttp connection to use
+ * @uri:       the URI to fetch
+ * @local:     the local name to give to the file
+ * @mode:      the update type to use when fetching data
+ * @callback:  callback to call when a chunk of data is received
+ * @user_data: user data to pass to the callback
+ *
+ * Fetch a file from the cache. Whether the file is actually loaded from the
+ * remote server depends on the value of @mode.
+ *
+ * Returns: The local path to the complete file
+ */
 /* TODO: use .part extentions and continue even when using GIS_ONCE */
 gchar *gis_http_fetch(GisHttp *http, const gchar *uri, const char *local,
 		GisCacheType mode, GisChunkCallback callback, gpointer user_data)
diff --git a/src/data/gis-http.h b/src/data/gis-http.h
index c042a42..b7f1638 100644
--- a/src/data/gis-http.h
+++ b/src/data/gis-http.h
@@ -28,26 +28,10 @@ typedef struct _GisHttp {
 	gchar *prefix;
 } GisHttp;
 
-/**
- * @param prefix The cache prefix: e.g. /nexrad/level2/
- * @return The HTTP connection handle
- */
 GisHttp *gis_http_new(const gchar *prefix);
 
-/**
- * Free data associated with the GisHttp
- * @param http the GisHttp to free
- */
 void gis_http_free(GisHttp *http);
 
-/**
- * @param http      GisHttp connection to use
- * @param uri       The uri to fetch
- * @param mode      Update type
- * @param callback  Callback to call when a chunck is recieved
- * @param user_data Data to pass to callback
- * @return The local path to the complete file
- */
 gchar *gis_http_fetch(GisHttp *http, const gchar *uri, const gchar *local,
 		GisCacheType mode,
 		GisChunkCallback callback,
-- 
2.43.2