Document GisHttp

diff --git a/src/data/gis-http.c b/src/data/gis-http.c
index e64d5ba9854616f0b605471543e6f6902af6470e..fb742c7e0e8d1d8b5c0d3981226c7e45cc197902 100644 (file)
--- 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 c042a42a7a6e32ce306a478d9c8ed7daaf53c364..b7f1638d7d4592e1845d3d1e1262ab5939b1709f 100644 (file)
--- 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,