[libchamplain] Document all ChamplainMapDataSources

[Pierre-Luc Beaudoin <plbeaudoin src gnome org>]

commit 9013209d309eed480aebd84acb9dc81e0ac145f1
Author: Simon Wenner <simon wenner ch>
Date:   Fri Jul 31 20:33:51 2009 +0200

    Document all ChamplainMapDataSources

 champlain/champlain-local-map-data-source.c   |   20 ++++++++++++++++++++
 champlain/champlain-map-data-source.c         |   22 ++++++++++++++++++++--
 champlain/champlain-network-map-data-source.c |   17 ++++++++++-------
 3 files changed, 50 insertions(+), 9 deletions(-)
---
diff --git a/champlain/champlain-local-map-data-source.c b/champlain/champlain-local-map-data-source.c
index e6cf210..d241310 100644
--- a/champlain/champlain-local-map-data-source.c
+++ b/champlain/champlain-local-map-data-source.c
@@ -16,6 +16,17 @@
  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  */
 
+/**
+ * SECTION:champlain-local-map-data-source
+ * @short_description: ChamplainLocalMapDataSource loads local data for
+ *  ChamplainMemphisMapSource.
+ *
+ * This map data source loads local <ulink role="online-location"
+ *  url="http://wiki.openstreetmap.org/wiki/.osm";>
+ * OpenStreetMap XML data files</ulink> (*.osm).
+ *
+ */
+
 #include "champlain-local-map-data-source.h"
 
 #define DEBUG_FLAG CHAMPLAIN_DEBUG_MEMPHIS
@@ -117,6 +128,15 @@ champlain_local_map_data_source_new (void)
   return g_object_new (CHAMPLAIN_TYPE_LOCAL_MAP_DATA_SOURCE, NULL);
 }
 
+/**
+ * champlain_local_map_data_source_load_map_data:
+ * @data_source: a #ChamplainLocalMapDataSource
+ * @map_path: a path to a map data file
+ *
+ * Loads the OpenStreetMap XML file at the given path.
+ *
+ * Since: 0.6
+ */
 void
 champlain_local_map_data_source_load_map_data (ChamplainLocalMapDataSource *self,
     const gchar *map_path)
diff --git a/champlain/champlain-map-data-source.c b/champlain/champlain-map-data-source.c
index 5477fd4..a916f1f 100644
--- a/champlain/champlain-map-data-source.c
+++ b/champlain/champlain-map-data-source.c
@@ -16,6 +16,15 @@
  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  */
 
+/**
+ * SECTION:champlain-map-data-source
+ * @short_description: Base class for map data sources.
+ *
+ * ChamplainMapDataSource provides the interface for
+ *  #ChamplainMemphisMapSource to aquire map data.
+ *
+ */
+
 #include "champlain-map-data-source.h"
 
 #define DEBUG_FLAG CHAMPLAIN_DEBUG_MEMPHIS
@@ -133,7 +142,7 @@ champlain_map_data_source_class_init (ChamplainMapDataSourceClass *klass)
   klass->get_map_data = champlain_map_data_source_real_get_map_data;
 
   /**
-  * ChamplainMapDataSource:Bounding-box:
+  * ChamplainMapDataSource:bounding-box:
   *
   * The bounding box of the area that contains map data.
   *
@@ -148,7 +157,7 @@ champlain_map_data_source_class_init (ChamplainMapDataSourceClass *klass)
         G_PARAM_READWRITE));
 
   /**
-  * ChamplainMapDataSource:state
+  * ChamplainMapDataSource:state:
   *
   * The map data source's state. Useful to know if the data source is loading
   * or not.
@@ -179,12 +188,21 @@ champlain_map_data_source_init (ChamplainMapDataSource *self)
   priv->state = CHAMPLAIN_STATE_INIT;
 }
 
+// TODO: should this class be instantiable?
 ChamplainMapDataSource *
 champlain_map_data_source_new (void)
 {
   return g_object_new (CHAMPLAIN_TYPE_MAP_DATA_SOURCE, NULL);
 }
 
+/**
+ * champlain_map_data_source_get_map_data:
+ * @data_source: a #ChamplainMapDataSource
+ *
+ * Returns the #MemphisMap of the data source.
+ *
+ * Since: 0.6
+ */
 MemphisMap *
 champlain_map_data_source_get_map_data (ChamplainMapDataSource *self)
 {
diff --git a/champlain/champlain-network-map-data-source.c b/champlain/champlain-network-map-data-source.c
index bf195f6..382e697 100644
--- a/champlain/champlain-network-map-data-source.c
+++ b/champlain/champlain-network-map-data-source.c
@@ -24,7 +24,8 @@
  * This map data source downloads the map data from an OpenStreetMap API
  * server. It supports protocol version 0.5 and 0.6.
  *
- * http://wiki.openstreetmap.org/wiki/API
+ * <ulink role="online-location" url="http://wiki.openstreetmap.org/wiki/API";>
+ * http://wiki.openstreetmap.org/wiki/API</ulink>
  *
  */
 
@@ -186,7 +187,7 @@ champlain_network_map_data_source_class_init (ChamplainNetworkMapDataSourceClass
         G_PARAM_READWRITE));
 
   /**
-  * ChamplainNetworkMapDataSource:proxy-uri
+  * ChamplainNetworkMapDataSource:proxy-uri:
   *
   * The proxy URI to use to access network
   *
@@ -269,7 +270,7 @@ load_map_data_cb (SoupSession *session, SoupMessage *msg,
 
 /**
  * champlain_network_map_data_source_load_map_data:
- * @source: the #ChamplainNetworkMapDataSource
+ * @source: a #ChamplainNetworkMapDataSource
  * @bound_left: the left bound in degree
  * @bound_buttom: the lower bound in degree
  * @bound_right: the right bound in degree
@@ -279,7 +280,9 @@ load_map_data_cb (SoupSession *session, SoupMessage *msg,
  * The box must not exceed an edge size of 0.25 degree. There are also
  * limitations on the maximum number of nodes that can be requested.
  *
- * For details, see: http://api.openstreetmap.org/api/capabilities
+ * For details, see: <ulink role="online-location"
+ *  url="http://api.openstreetmap.org/api/capabilities";>
+ * http://api.openstreetmap.org/api/capabilities</ulink>
  *
  * Since: 0.6
  */
@@ -331,7 +334,7 @@ champlain_network_map_data_source_load_map_data (
 
 /**
  * champlain_network_map_data_source_get_api_uri:
- * @source: the #ChamplainNetworkMapDataSource
+ * @source: a #ChamplainNetworkMapDataSource
  *
  * Returns the URI of the API server.
  *
@@ -350,8 +353,8 @@ champlain_network_map_data_source_get_api_uri (
 
 /**
  * champlain_network_map_data_source_set_api_uri:
- * @source: the #ChamplainNetworkMapDataSource
- * @api_uri: the URI of the API server
+ * @source: a #ChamplainNetworkMapDataSource
+ * @api_uri: an URI of an API server
  *
  * Sets the URI of the API server.
  *