Improve documenation of base marker and map source

diff --git a/champlain/champlain-base-marker.c b/champlain/champlain-base-marker.c
index 234b2ad66adcededceb9fd10d2b35273d459c593..c7f9ae8692e27c9fb42f533d2b2f3b2c147d5b76 100644 (file)
--- a/champlain/champlain-base-marker.c
+++ b/champlain/champlain-base-marker.c
@@ -18,19 +18,19 @@
 
 /**
  * SECTION:champlain-base-marker
- * @short_description: A base marker to identify points of interest on a map
+ * @short_description: a base marker to identify points of interest on a map
  *
- * Base markers reprensent points of interest on a map. Base markers need to be
- * placed on a layer (a #ClutterGroup).  Layers have to be added to a
- * #ChamplainView for the base_markers to show on the map.
+ * Base markers reprensent points of interest on a map. base markers need to be
+ * placed on a layer (a #cluttergroup).  layers have to be added to a
+ * #champlainview for the base_markers to show on the map.
  *
- * A basemarker is nothing more than a regular #ClutterActor.  You can draw on
- * it what ever you want.  Don't forget to set the anchor position in the base
- * marker using #clutter_actor_set_anchor_point. Set the base_markers position
+ * a basemarker is nothing more than a regular #clutteractor.  you can draw on
+ * it what ever you want.  don't forget to set the anchor position in the base
+ * marker using #clutter_actor_set_anchor_point. set the base_markers position
  * on the map using #champlain_base_marker_set_position.
  *
- * Champlain has a more evoluted type of markers with text and image support.
- * See #ChamplainMarker.
+ * champlain has a more evoluted type of markers with text and image support.
+ * see #champlainmarker.
  */
 
 #include "config.h"

diff --git a/champlain/champlain-map-source.c b/champlain/champlain-map-source.c
index 7c0773ed23284ef7ec623d63b62f5c8819a671e3..ef9765b1067d63cae1c83bfa8e31d23038ff0e25 100644 (file)
--- a/champlain/champlain-map-source.c
+++ b/champlain/champlain-map-source.c
@@ -16,6 +16,20 @@
  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  */
 
+/**
+ * SECTION:champlain-map-source
+ * @short_description: A base class for map sources
+ *
+ * #ChamplainTiles come from map sources which are represented by
+ * #ChamplainMapSource.  This is should be considered an abstract
+ * type as it does nothing of interest.
+ *
+ * When loading new tiles, #ChamplainView calls #champlain_map_source_get_tile
+ * on the current #ChamplainMapSource passing it a #ChamplainTile to be filled
+ * with the image.  #ChamplainMapSources should check with #ChamplainCache
+ * if the image is already locally available with #champlain_cache_fill_tile.
+ */
+
 #include "config.h"
 
 #define DEBUG_FLAG CHAMPLAIN_DEBUG_LOADING
@@ -264,14 +278,14 @@ champlain_map_source_class_init (ChamplainMapSourceClass *klass)
   g_object_class_install_property (object_class, PROP_TILE_SIZE, pspec);
 
   /**
-  * ChamplainMapSource:map-projection
+  * ChamplainMapSource:projection
   *
   * The map projection of the map source
   *
   * Since: 0.4
   */
-  pspec = g_param_spec_enum ("map-projection",
-                             "Map Projection",
+  pspec = g_param_spec_enum ("projection",
+                             "Projection",
                              "The map projection",
                              CHAMPLAIN_TYPE_MAP_PROJECTION,
                              CHAMPLAIN_MAP_PROJECTION_MERCATOR,
@@ -286,6 +300,14 @@ champlain_map_source_init (ChamplainMapSource *champlainMapSource)
   champlainMapSource->priv = priv;
 }
 
+/**
+ * champlain_map_source_get_max_zoom_level:
+ * @map_source: a #ChamplainMapSource
+ *
+ * Returns the maximum zoom level this map source supports
+ *
+ * Since: 0.4
+ */
 gint
 champlain_map_source_get_max_zoom_level (ChamplainMapSource *map_source)
 {
@@ -293,6 +315,14 @@ champlain_map_source_get_max_zoom_level (ChamplainMapSource *map_source)
   return priv->max_zoom_level;
 }
 
+/**
+ * champlain_map_source_get_min_zoom_level:
+ * @map_source: a #ChamplainMapSource
+ *
+ * Returns the miminum zoom level this map source supports
+ *
+ * Since: 0.4
+ */
 gint
 champlain_map_source_get_min_zoom_level (ChamplainMapSource *map_source)
 {
@@ -300,6 +330,14 @@ champlain_map_source_get_min_zoom_level (ChamplainMapSource *map_source)
   return priv->min_zoom_level;
 }
 
+/**
+ * champlain_map_source_get_tile_size:
+ * @map_source: a #ChamplainMapSource
+ *
+ * Returns the tile's size (width and height) in pixels for this map source
+ *
+ * Since: 0.4
+ */
 guint
 champlain_map_source_get_tile_size (ChamplainMapSource *map_source)
 {
@@ -307,6 +345,17 @@ champlain_map_source_get_tile_size (ChamplainMapSource *map_source)
   return priv->tile_size;
 }
 
+/**
+ * champlain_map_source_get_x:
+ * @map_source: a #ChamplainMapSource
+ * @zoom_level: the zoom level
+ * @longitude: a longitude
+ *
+ * Returns the x position on the map using this map source's projection.
+ * (0, 0) is located at the top left.
+ *
+ * Since: 0.4
+ */
 guint
 champlain_map_source_get_x (ChamplainMapSource *map_source,
     gint zoom_level,
@@ -317,6 +366,17 @@ champlain_map_source_get_x (ChamplainMapSource *map_source,
   return ((longitude + 180.0) / 360.0 * pow(2.0, zoom_level)) * priv->tile_size;
 }
 
+/**
+ * champlain_map_source_get_y:
+ * @map_source: a #ChamplainMapSource
+ * @zoom_level: the zoom level
+ * @latitude: a latitude
+ *
+ * Returns the y position on the map using this map source's projection.
+ * (0, 0) is located at the top left.
+ *
+ * Since: 0.4
+ */
 guint
 champlain_map_source_get_y (ChamplainMapSource *map_source,
     gint zoom_level,
@@ -329,6 +389,15 @@ champlain_map_source_get_y (ChamplainMapSource *map_source,
         M_PI) / 2.0 * pow (2.0, zoom_level)) * priv->tile_size;
 }
 
+/**
+ * champlain_map_source_get_row_count:
+ * @map_source: a #ChamplainMapSource
+ * @zoom_level: the zoom level
+ *
+ * Returns the number of tiles in a row at this zoom level for this map source.
+ *
+ * Since: 0.4
+ */
 guint
 champlain_map_source_get_row_count (ChamplainMapSource *map_source,
     gint zoom_level)
@@ -338,6 +407,16 @@ champlain_map_source_get_row_count (ChamplainMapSource *map_source,
   return pow (2, zoom_level);
 }
 
+/**
+ * champlain_map_source_get_column_count:
+ * @map_source: a #ChamplainMapSource
+ * @zoom_level: the zoom level
+ *
+ * Returns the number of tiles in a column at this zoom level for this map
+ * source.
+ *
+ * Since: 0.4
+ */
 guint
 champlain_map_source_get_column_count (ChamplainMapSource *map_source,
     gint zoom_level)
@@ -347,6 +426,16 @@ champlain_map_source_get_column_count (ChamplainMapSource *map_source,
   return pow (2, zoom_level);
 }
 
+/**
+ * champlain_map_source_fill_tile:
+ * @map_source: a #ChamplainMapSource
+ * @tile: A #ChamplainTile
+ *
+ * Fills the tile with image data (either from cache, network or rendered
+ * locally).
+ *
+ * Since: 0.4
+ */
 void
 champlain_map_source_fill_tile (ChamplainMapSource *map_source,
     ChamplainTile *tile)
@@ -363,6 +452,17 @@ champlain_map_source_real_fill_tile (ChamplainMapSource *map_source,
   g_error ("Should not be reached");
 }
 
+/**
+ * champlain_map_source_get_longitude:
+ * @map_source: a #ChamplainMapSource
+ * @zoom_level: the zoom level
+ * @x: a x position
+ *
+ * Returns the longitude corresponding to this x position in the map source's
+ * projection.
+ *
+ * Since: 0.4
+ */
 gdouble
 champlain_map_source_get_longitude (ChamplainMapSource *map_source,
     gint zoom_level,
@@ -374,6 +474,17 @@ champlain_map_source_get_longitude (ChamplainMapSource *map_source,
   return dx / pow (2.0, zoom_level) * 360.0 - 180;
 }
 
+/**
+ * champlain_map_source_get_latitude:
+ * @map_source: a #ChamplainMapSource
+ * @zoom_level: the zoom level
+ * @y: a y position
+ *
+ * Returns the latitude corresponding to this y position in the map source's
+ * projection.
+ *
+ * Since: 0.4
+ */
 gdouble
 champlain_map_source_get_latitude (ChamplainMapSource *map_source,
     gint zoom_level,
@@ -386,6 +497,14 @@ champlain_map_source_get_latitude (ChamplainMapSource *map_source,
   return 180.0 / M_PI * atan (0.5 * (exp (n) - exp (-n)));
 }
 
+/**
+ * champlain_map_source_get_name:
+ * @map_source: a #ChamplainMapSource
+ *
+ * Returns the map source's name.
+ *
+ * Since: 0.4
+ */
 const gchar *
 champlain_map_source_get_name (ChamplainMapSource *map_source)
 {
@@ -393,6 +512,15 @@ champlain_map_source_get_name (ChamplainMapSource *map_source)
   return priv->name;
 }
 
+/**
+ * champlain_map_source_set_name:
+ * @map_source: a #ChamplainMapSource
+ * @name: a name
+ *
+ * Sets the map source's name.
+ *
+ * Since: 0.4
+ */
 void
 champlain_map_source_set_name (ChamplainMapSource *map_source,
     const gchar *name)
@@ -401,8 +529,17 @@ champlain_map_source_set_name (ChamplainMapSource *map_source,
 
   g_free (priv->name);
   priv->name = g_strdup (name);
+  g_object_notify (G_OBJECT (map_source), "name");
 }
 
+/**
+ * champlain_map_source_get_license:
+ * @map_source: a #ChamplainMapSource
+ *
+ * Returns the map source's license.
+ *
+ * Since: 0.4
+ */
 const gchar *
 champlain_map_source_get_license (ChamplainMapSource *map_source)
 {
@@ -410,6 +547,15 @@ champlain_map_source_get_license (ChamplainMapSource *map_source)
   return priv->license;
 }
 
+/**
+ * champlain_map_source_set_license:
+ * @map_source: a #ChamplainMapSource
+ * @license: the licence
+ *
+ * Sets the map source's license.
+ *
+ * Since: 0.4
+ */
 void
 champlain_map_source_set_license (ChamplainMapSource *map_source,
     const gchar *license)
@@ -418,5 +564,77 @@ champlain_map_source_set_license (ChamplainMapSource *map_source,
 
   g_free (priv->license);
   priv->license = g_strdup (license);
+  g_object_notify (G_OBJECT (map_source), "license");
+}
+
+/**
+ * champlain_map_source_get_license_uri:
+ * @map_source: a #ChamplainMapSource
+ *
+ * Returns the map source's license URI.
+ *
+ * Since: 0.4
+ */
+const gchar *
+champlain_map_source_get_license_uri (ChamplainMapSource *map_source)
+{
+  ChamplainMapSourcePrivate *priv = map_source->priv;
+
+  return priv->license_uri;
+}
+
+/**
+ * champlain_map_source_set_license_uri:
+ * @map_source: a #ChamplainMapSource
+ * @license_uri: the licence URI
+ *
+ * Sets the map source's license URI.
+ *
+ * Since: 0.4
+ */
+void
+champlain_map_source_set_license_uri (ChamplainMapSource *map_source,
+    const gchar *license_uri)
+{
+  ChamplainMapSourcePrivate *priv = map_source->priv;
+
+  g_free (priv->license_uri);
+  priv->license = g_strdup (license_uri);
+  g_object_notify (G_OBJECT (map_source), "license-uri");
+}
+
+/**
+ * champlain_map_source_get_projection:
+ * @map_source: a #ChamplainMapSource
+ *
+ * Returns the map source's projection.
+ *
+ * Since: 0.4
+ */
+ChamplainMapProjection
+champlain_map_source_get_projection (ChamplainMapSource *map_source)
+{
+  ChamplainMapSourcePrivate *priv = map_source->priv;
+
+  return priv->map_projection;
+}
+
+/**
+ * champlain_map_source_set_projection:
+ * @map_source: a #ChamplainMapSource
+ * @projection: a #ChamplainMapProjection
+ *
+ * Sets the map source's projection.
+ *
+ * Since: 0.4
+ */
+void
+champlain_map_source_set_projection (ChamplainMapSource *map_source,
+    ChamplainMapProjection projection)
+{
+  ChamplainMapSourcePrivate *priv = map_source->priv;
+
+  priv->map_projection = projection;
+  g_object_notify (G_OBJECT (map_source), "projection");
 }
 

diff --git a/champlain/champlain-map-source.h b/champlain/champlain-map-source.h
index 5d02d1a884115dd41559bc3d87fbd4ecacf79143..8c821164908f1a4813f72f000133e93ea09450e5 100644 (file)
--- a/champlain/champlain-map-source.h
+++ b/champlain/champlain-map-source.h
@@ -102,6 +102,14 @@ void champlain_map_source_set_license (ChamplainMapSource *map_source,
     const gchar *license);
 const gchar * champlain_map_source_get_license (ChamplainMapSource *map_source);
 
+void champlain_map_source_set_license_uri (ChamplainMapSource *map_source,
+    const gchar *license_uri);
+const gchar * champlain_map_source_get_license_uri (ChamplainMapSource *map_source);
+
+void champlain_map_source_set_projection (ChamplainMapSource *map_source,
+    ChamplainMapProjection projection);
+ChamplainMapProjection champlain_map_source_get_projection (ChamplainMapSource *map_source);
+
 G_END_DECLS
 
 #endif

diff --git a/champlain/champlain-network-map-source.c b/champlain/champlain-network-map-source.c
index 46af8ed5720725aeb060b6018f8e3a8b95440171..0abb19872d9732de8a16474a08784d5de4d217d0 100644 (file)
--- a/champlain/champlain-network-map-source.c
+++ b/champlain/champlain-network-map-source.c
@@ -230,7 +230,7 @@ champlain_network_map_source_new_full (const gchar *name,
   network_map_source = g_object_new (CHAMPLAIN_TYPE_NETWORK_MAP_SOURCE, "name", name,
       "license", license, "license-uri", license_uri,
       "min-zoom-level", min_zoom, "max-zoom-level", max_zoom,
-      "tile-size", tile_size, "map-projection", projection,
+      "tile-size", tile_size, "projection", projection,
       "uri-format", uri_format, NULL);
   return network_map_source;
 }

diff --git a/docs/reference/libchamplain-docs.sgml b/docs/reference/libchamplain-docs.sgml
index 236498b2fea18585c3e0f5aef9a625872c978ea2..0d89f0f4c2c99c1c35eaf67d311cc92518476f60 100644 (file)
--- a/docs/reference/libchamplain-docs.sgml
+++ b/docs/reference/libchamplain-docs.sgml
@@ -40,20 +40,24 @@
 
   <chapter>
     <title>I. View API Reference</title>
-    <xi:include href="xml/champlain.xml"/>
     <xi:include href="xml/champlain-view.xml"/>
     <xi:include href="xml/champlain-layer.xml"/>
     <xi:include href="xml/champlain-base-marker.xml"/>
     <xi:include href="xml/champlain-marker.xml"/>
-    <xi:include href="xml/champlain-version.xml"/>
   </chapter>
   <chapter>
     <title>II. Map Source API Reference</title>
+    <xi:include href="xml/champlain-map-source-factory.xml"/>
     <xi:include href="xml/champlain-map-source.xml"/>
     <xi:include href="xml/champlain-network-map-source.xml"/>
     <xi:include href="xml/champlain-tile.xml"/>
     <xi:include href="xml/champlain-cache.xml"/>
   </chapter>
+  <chapter>
+    <title>III. Utility API Reference</title>
+    <xi:include href="xml/champlain.xml"/>
+    <xi:include href="xml/champlain-version.xml"/>
+  </chapter>
   <index>
     <title>Index</title>
   </index>

diff --git a/docs/reference/libchamplain-sections.txt b/docs/reference/libchamplain-sections.txt
index 29831b0dd13db5bb71660d4f0f555d3de41ee2a5..7c50ab1b2fe1c5b72c7837333f9c20aa484aafc6 100644 (file)
--- a/docs/reference/libchamplain-sections.txt
+++ b/docs/reference/libchamplain-sections.txt
@@ -17,6 +17,10 @@ champlain_map_source_set_name
 champlain_map_source_get_name
 champlain_map_source_set_license
 champlain_map_source_get_license
+champlain_map_source_set_license_uri
+champlain_map_source_get_license_uri
+champlain_map_source_set_projection
+champlain_map_source_get_projection
 <SUBSECTION Standard>
 CHAMPLAIN_MAP_SOURCE
 CHAMPLAIN_IS_MAP_SOURCE
@@ -157,7 +161,7 @@ champlain_map_source_new_osm_osmarender
 champlain_map_source_new_oam
 champlain_map_source_new_mff_relief
 champlain_network_map_source_get_tile_uri
-champlain_network_map_source_set_tile_uri
+champlain_network_map_source_set_uri_format
 champlain_network_map_source_fill_tile
 <SUBSECTION Standard>
 CHAMPLAIN_NETWORK_MAP_SOURCE
@@ -296,16 +300,43 @@ ChamplainState
 
 <SECTION>
 <FILE>champlain-cache</FILE>
+<TITLE>ChamplainCache</TITLE>
 ChamplainCache
 ChamplainCacheClass
 champlain_cache_fill_tile
 champlain_cache_get_default
 champlain_cache_get_size_limit
-champlain_cache_get_type
 champlain_cache_purge
 champlain_cache_purge_on_idle
 champlain_cache_set_size_limit
 champlain_cache_tile_is_expired
 champlain_cache_update_tile
+<SUBSECTION Standard>
+CHAMPLAIN_CACHE
+CHAMPLAIN_IS_CACHE
+CHAMPLAIN_TYPE_CACHE
+champlain_cache_get_type
+CHAMPLAIN_CACHE_CLASS
+CHAMPLAIN_IS_CACHE_CLASS
+CHAMPLAIN_CACHE_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>champlain-map-source-factory</FILE>
+<TITLE>ChamplainMapSourceFactory</TITLE>
+ChamplainMapSourceFactory
+ChamplainMapSourceConstructor
+champlain_map_source_factory_get_default
+champlain_map_source_factory_get_list
+champlain_map_source_factory_create
+champlain_map_source_factory_register
+<SUBSECTION Standard>
+CHAMPLAIN_MAP_SOURCE_FACTORY
+CHAMPLAIN_IS_MAP_SOURCE_FACTORY
+CHAMPLAIN_TYPE_MAP_SOURCE_FACTORY
+champlain_map_source_factory_get_type
+CHAMPLAIN_MAP_SOURCE_FACTORY_CLASS
+CHAMPLAIN_IS_MAP_SOURCE_FACTORY_CLASS
+CHAMPLAIN_MAP_SOURCE_FACTORY_GET_CLASS
 </SECTION>
 

diff --git a/docs/reference/libchamplain.types b/docs/reference/libchamplain.types
index db399955f2ee65a468da434eccfd42ed5f45a158..e460bc84fb46c2512ba23c45f3ec99d4bff36fcb 100644 (file)
--- a/docs/reference/libchamplain.types
+++ b/docs/reference/libchamplain.types
@@ -8,3 +8,4 @@ champlain_map_source_get_type
 champlain_network_map_source_get_type
 champlain_tile_get_type
 champlain_cache_get_type
+champlain_map_source_factory_get_type