[libchamplain] Update documentation

From: Jiří Techet <jiritechet src gnome org>
To: commits-list gnome org
Cc:
Subject: [libchamplain] Update documentation
Date: Mon, 14 Feb 2011 23:22:52 +0000 (UTC)
commit 383c5d344033779218f9db3fc771ac79e064b304
Author: JiÅ?Ã Techet <techet gmail com>
Date:   Mon Feb 14 22:54:30 2011 +0100

    Update documentation

 champlain/champlain-bounding-box.h       |    1 +
 champlain/champlain-coordinate.c         |   37 ++++++++-----
 champlain/champlain-custom-marker.c      |    4 +-
 champlain/champlain-group.c              |    2 +-
 champlain/champlain-location.c           |   58 ++++++++++++++------
 champlain/champlain-location.h           |   32 +++++++++++
 champlain/champlain-marker-layer.c       |    7 +--
 champlain/champlain-marker.c             |    4 +-
 champlain/champlain-marker.h             |    1 -
 champlain/champlain-path-layer.c         |   38 ++++++-------
 docs/reference/libchamplain-docs.sgml    |    9 +++-
 docs/reference/libchamplain-sections.txt |   86 ++++++++++++++++++++++++------
 12 files changed, 200 insertions(+), 79 deletions(-)
---
diff --git a/champlain/champlain-bounding-box.h b/champlain/champlain-bounding-box.h
index 12fbe60..874519f 100644
--- a/champlain/champlain-bounding-box.h
+++ b/champlain/champlain-bounding-box.h
@@ -44,6 +44,7 @@ typedef struct _ChamplainBoundingBox ChamplainBoundingBox;
  */
 struct _ChamplainBoundingBox
 {
+  /*< public >*/
   gdouble left;
   gdouble top;
   gdouble right;
diff --git a/champlain/champlain-coordinate.c b/champlain/champlain-coordinate.c
index f768895..5def650 100644
--- a/champlain/champlain-coordinate.c
+++ b/champlain/champlain-coordinate.c
@@ -18,18 +18,9 @@
 
 /**
  * SECTION:champlain-coordinate
- * @short_description: A marker to identify points of interest on a map
- *
- * Markers reprensent points of interest on a map. Markers need to be
- * placed on a layer (a #ChamplainMarkerLayer). Layers have to be added to a
- * #champlainview for the markers to show on the map.
- *
- * A marker is nothing more than a regular #clutteractor. You can draw on
- * it what ever you want.  Set the markers position
- * on the map using #champlain_location_set_position.
- *
- * libchamplain has a more evoluted type of markers with text and image support.
- * See #ChamplainLabel.
+ * @short_description: The simpliest implementation of #ChamplainLocation
+ * 
+ * #ChamplainCoordinate is a simple object implementing #ChamplainLocation.
  */
 
 #include "champlain-coordinate.h"
@@ -218,7 +209,15 @@ champlain_coordinate_init (ChamplainCoordinate *coordinate)
   priv->lon = 0;
 }
 
-
+/**
+ * champlain_coordinate_new:
+ *
+ * Creates a new instance of #ChamplainCoordinate.
+ *
+ * Returns: the created instance.
+ *
+ * Since: 0.10
+ */
 ChamplainCoordinate *
 champlain_coordinate_new ()
 {
@@ -226,6 +225,18 @@ champlain_coordinate_new ()
 }
 
 
+/**
+ * champlain_coordinate_new_full:
+ * @latitude: the latitude coordinate
+ * @longitude: the longitude coordinate
+ * 
+ * Creates a new instance of #ChamplainCoordinate initialized with the given 
+ * coordinates.
+ *
+ * Returns: the created instance.
+ *
+ * Since: 0.10
+ */
 ChamplainCoordinate *
 champlain_coordinate_new_full (gdouble latitude, 
     gdouble longitude)
diff --git a/champlain/champlain-custom-marker.c b/champlain/champlain-custom-marker.c
index e142c29..77b2919 100644
--- a/champlain/champlain-custom-marker.c
+++ b/champlain/champlain-custom-marker.c
@@ -18,10 +18,10 @@
 
 /**
  * SECTION:champlain-custom-marker
- * @short_description: #ChamplainCustom marker is a marker implementing the
+ * @short_description: #ChamplainCustomMarker is a marker implementing the
  * #ClutterContainer interface. 
  * 
- * #ChamplainCustom marker is a marker implementing the #ClutterContainer 
+ * #ChamplainCustomMarker is a marker implementing the #ClutterContainer 
  * interface. You can insert your custom actors into the container. Don't forget 
  * to set the anchor position in the marker using #clutter_actor_set_anchor_point.
  */
diff --git a/champlain/champlain-group.c b/champlain/champlain-group.c
index 189dbf9..d7ae605 100644
--- a/champlain/champlain-group.c
+++ b/champlain/champlain-group.c
@@ -23,7 +23,7 @@
  *
  */
 
-/**
+/*
  * SECTION:champlain-group
  * @short_description: A fixed layout container
  *
diff --git a/champlain/champlain-location.c b/champlain/champlain-location.c
index 108def6..22bce1c 100644
--- a/champlain/champlain-location.c
+++ b/champlain/champlain-location.c
@@ -1,8 +1,32 @@
+/*
+ * Copyright (C) 2011 Jiri Techet <techet gmail com>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+ */
+
+/**
+ * SECTION:champlain-location
+ * @short_description: An interface common to objects having latitude and longitude
+ * 
+ * By implementing #ChamplainLocation the object declares that it has latitude
+ * and longitude and can be used to specify location on the map.
+ */
 
 #include "champlain-location.h"
 #include "champlain-private.h"
 
-
 static void
 champlain_location_base_init (gpointer g_iface)
 {
@@ -11,27 +35,27 @@ champlain_location_base_init (gpointer g_iface)
   if (!initialized)
     {
       /**
-       * ChamplainMarker:longitude:
+       * ChamplainLocation:longitude:
        *
-       * The longitude coordonate of the map
+       * The longitude coordonate
        *
        * Since: 0.10
        */
       g_object_interface_install_property (g_iface,
           g_param_spec_double ("longitude", "Longitude",
-              "The longitude coordonate of the marker",
+              "The longitude coordonate",
               -180.0f, 180.0f, 0.0f, CHAMPLAIN_PARAM_READWRITE));
 
       /**
-       * ChamplainMarker:latitude:
+       * ChamplainLocation:latitude:
        *
-       * The latitude coordonate of the map
+       * The latitude coordonate
        *
        * Since: 0.10
        */
       g_object_interface_install_property (g_iface,
           g_param_spec_double ("latitude", "Latitude",
-              "The latitude coordonate of the marker",
+              "The latitude coordonate",
               -90.0f, 90.0f, 0.0f, CHAMPLAIN_PARAM_READWRITE));
 
       initialized = TRUE;
@@ -60,11 +84,11 @@ champlain_location_get_type (void)
 
 /**
  * champlain_location_set_position:
- * @marker: a #ChamplainMarker
- * @latitude: the longitude to center the map at
- * @longitude: the longitude to center the map at
+ * @location: a #ChamplainLocation
+ * @latitude: the latitude
+ * @longitude: the longitude
  *
- * Positions the marker on the map at the coordinates
+ * Sets the coordinates of the location
  *
  * Since: 0.10
  */
@@ -81,11 +105,11 @@ champlain_location_set_position (ChamplainLocation *location,
 
 /**
  * champlain_location_get_latitude:
- * @marker: a #ChamplainMarker
+ * @location: a #ChamplainLocation
  *
- * Gets the latitude of the marker.
+ * Gets the latitude coordinate.
  *
- * Returns: the latitude of the marker.
+ * Returns: the latitude coordinate.
  *
  * Since: 0.10
  */
@@ -98,11 +122,11 @@ champlain_location_get_latitude (ChamplainLocation *location)
 
 /**
  * champlain_location_get_longitude:
- * @marker: a #ChamplainMarker
+ * @location: a #ChamplainLocation
  *
- * Gets the longitude of the marker.
+ * Gets the longitude coordinate.
  *
- * Returns: the longitude of the marker.
+ * Returns: the longitude coordinate.
  *
  * Since: 0.10
  */
diff --git a/champlain/champlain-location.h b/champlain/champlain-location.h
index 9c5756c..3c52141 100644
--- a/champlain/champlain-location.h
+++ b/champlain/champlain-location.h
@@ -1,3 +1,20 @@
+/*
+ * Copyright (C) 2011 Jiri Techet <techet gmail com>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+ */
 
 #ifndef __CHAMPLAIN_LOCATION_H__
 #define __CHAMPLAIN_LOCATION_H__
@@ -11,13 +28,28 @@ G_BEGIN_DECLS
 #define CHAMPLAIN_IS_LOCATION(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), CHAMPLAIN_TYPE_LOCATION))
 #define CHAMPLAIN_LOCATION_GET_IFACE(inst) (G_TYPE_INSTANCE_GET_INTERFACE ((inst), CHAMPLAIN_TYPE_LOCATION, ChamplainLocationIface))
 
+/**
+ * ChamplainLocation:
+ *
+ * An interface common to objects having latitude and longitude.
+ */
 typedef struct _ChamplainLocation ChamplainLocation; /* Dummy object */
 typedef struct _ChamplainLocationIface ChamplainLocationIface;
 
+/**
+ * ChamplainLocationIface:
+ * @get_latitude: virtual function for obtaining latitude.
+ * @get_longitude: virtual function for obtaining longitude.
+ * @set_position: virtual function for setting position.
+ * 
+ * An interface common to objects having latitude and longitude.
+ */
 struct _ChamplainLocationIface
 {
+  /*< private >*/
   GTypeInterface parent;
 
+  /*< public >*/
   gdouble (* get_latitude) (ChamplainLocation *location);
   gdouble (* get_longitude) (ChamplainLocation *location);
   void (* set_position) (ChamplainLocation *location,
diff --git a/champlain/champlain-marker-layer.c b/champlain/champlain-marker-layer.c
index e8dc854..9af841a 100644
--- a/champlain/champlain-marker-layer.c
+++ b/champlain/champlain-marker-layer.c
@@ -20,11 +20,8 @@
  * SECTION:champlain-marker-layer
  * @short_description: A container for #ChamplainMarker
  *
- * A ChamplainMarkerLayer is little more than a #ClutterContainer. It keeps the
- * markers ordered so that they display correctly.
- *
- * Use #clutter_container_add to add markers to the layer and
- * #clutter_container_remove to remove them.
+ * A ChamplainMarkerLayer displays markers on the map. It is responsible for
+ * positioning markers correctly, marker selections and group marker operations. 
  */
 
 #include "config.h"
diff --git a/champlain/champlain-marker.c b/champlain/champlain-marker.c
index e5881af..448ff7c 100644
--- a/champlain/champlain-marker.c
+++ b/champlain/champlain-marker.c
@@ -29,8 +29,8 @@
  * it what ever you want.  Set the markers position
  * on the map using #champlain_location_set_position.
  *
- * libchamplain has a more evoluted type of markers with text and image support.
- * See #ChamplainLabel.
+ * This is a base abstract class of all markers. libchamplain has a more evoluted
+ * type of markers with text and image support. See #ChamplainLabel for more details.
  */
 
 #include "config.h"
diff --git a/champlain/champlain-marker.h b/champlain/champlain-marker.h
index 29b2509..e9567e3 100644
--- a/champlain/champlain-marker.h
+++ b/champlain/champlain-marker.h
@@ -70,7 +70,6 @@ struct _ChamplainMarkerClass
 GType champlain_marker_get_type (void);
 
 
-
 void champlain_marker_set_selectable (ChamplainMarker *marker,
     gboolean value);
 gboolean champlain_marker_get_selectable (ChamplainMarker *marker);
diff --git a/champlain/champlain-path-layer.c b/champlain/champlain-path-layer.c
index 8d5b930..45cf04a 100644
--- a/champlain/champlain-path-layer.c
+++ b/champlain/champlain-path-layer.c
@@ -18,13 +18,14 @@
 
 /**
  * SECTION:champlain-path-layer
- * @short_description: A container for #ChamplainLocation
+ * @short_description: A layer displaying line path between inserted #ChamplainLocation
+ * objects
  *
- * A ChamplainPathLayer is little more than a #ClutterContainer. It keeps the
- * paths ordered so that they display correctly.
- *
- * Use #clutter_container_add to add paths to the layer and
- * #clutter_container_remove to remove them.
+ * This layer shows a connection between inserted objects implementing the
+ * #ChamplainLocation interface. This means that both #ChamplainMarker
+ * objects and #ChamplainCoordinate objects can be inserted into the layer.
+ * Of course, custom objects implementing the #ChamplainLocation interface
+ * can be used as well.
  */
 
 #include "config.h"
@@ -477,11 +478,10 @@ champlain_path_layer_init (ChamplainPathLayer *self)
 
 /**
  * champlain_path_layer_new:
- * @mode: Selection mode
  *
  * Creates a new instance of #ChamplainPathLayer.
  *
- * Returns: a new #ChamplainPathLayer ready to be used as a container for the markers.
+ * Returns: a new instance of #ChamplainPathLayer.
  *
  * Since: 0.10
  */
@@ -492,8 +492,6 @@ champlain_path_layer_new ()
 }
 
 
-
-
 static void
 position_notify (ChamplainLocation *location,
     G_GNUC_UNUSED GParamSpec *pspec,
@@ -503,7 +501,6 @@ position_notify (ChamplainLocation *location,
 }
 
 
-
 static void
 add_node (ChamplainPathLayer *layer,
     ChamplainLocation *location,
@@ -533,7 +530,7 @@ add_node (ChamplainPathLayer *layer,
  * @layer: a #ChamplainPathLayer
  * @location: a #ChamplainLocation
  *
- * Adds the marker to the layer.
+ * Adds a #ChamplainLocation object to the layer.
  *
  * Since: 0.10
  */
@@ -552,11 +549,12 @@ champlain_path_layer_add_node (ChamplainPathLayer *layer,
  * champlain_path_layer_remove_all:
  * @layer: a #ChamplainPathLayer
  *
- * Removes all markers from the layer.
+ * Removes all #ChamplainLocation objects from the layer.
  *
  * Since: 0.10
  */
-void champlain_path_layer_remove_all (ChamplainPathLayer *layer)
+void 
+champlain_path_layer_remove_all (ChamplainPathLayer *layer)
 {
   ChamplainPathLayerPrivate *priv = GET_PRIVATE (layer);
   GList *elem;
@@ -582,7 +580,7 @@ void champlain_path_layer_remove_all (ChamplainPathLayer *layer)
  * champlain_path_layer_get_nodes:
  * @layer: a #ChamplainPathLayer
  *
- * Gets a copy of the list of all markers inserted into the layer. You should
+ * Gets a copy of the list of all #ChamplainLocation objects inserted into the layer. You should
  * free the list but not its contents.
  * 
  * Returns: (transfer container) (element-type ChamplainLocation): the list
@@ -603,7 +601,7 @@ champlain_path_layer_get_nodes (ChamplainPathLayer *layer)
  * @layer: a #ChamplainPathLayer
  * @location: a #ChamplainLocation
  *
- * Removes the marker from the layer.
+ * Removes the #ChamplainLocation object from the layer.
  *
  * Since: 0.10
  */
@@ -629,9 +627,9 @@ champlain_path_layer_remove_node (ChamplainPathLayer *layer,
  * champlain_path_layer_insert_node:
  * @layer: a #ChamplainPathLayer
  * @location: a #ChamplainLocation
- * @position: position in the list where the marker should be inserted
+ * @position: position in the list where the #ChamplainLocation object should be inserted
  *
- * Inserts a marker to the specified position.
+ * Inserts a #ChamplainLocation object to the specified position.
  *
  * Since: 0.10
  */
@@ -780,12 +778,10 @@ set_view (ChamplainLayer *layer,
  * champlain_path_layer_get_bounding_box:
  * @layer: a #ChamplainPathLayer
  *
- * Gets the bounding box occupied by the markers in the layer
+ * Gets the bounding box occupied by the #ChamplainLocation objects in the layer
  *
  * Returns: The bounding box.
  * 
- * FIXME: This doesn't take into account the marker's actor size yet
- *
  * Since: 0.10
  */
 ChamplainBoundingBox *
diff --git a/docs/reference/libchamplain-docs.sgml b/docs/reference/libchamplain-docs.sgml
index 41876ac..5b72a2e 100644
--- a/docs/reference/libchamplain-docs.sgml
+++ b/docs/reference/libchamplain-docs.sgml
@@ -45,17 +45,24 @@
     <xi:include href="xml/champlain-view.xml"/>
   </part>
   <part>
-    <title>Layers and Markers</title>
+    <title>Layers, Markers and Locations</title>
     <chapter>
       <title>Layers</title>
       <xi:include href="xml/champlain-layer.xml"/>
       <xi:include href="xml/champlain-marker-layer.xml"/>
+      <xi:include href="xml/champlain-path-layer.xml"/>
     </chapter>
     <chapter>
       <title>Markers</title>
       <xi:include href="xml/champlain-marker.xml"/>
       <xi:include href="xml/champlain-label.xml"/>
       <xi:include href="xml/champlain-point.xml"/>
+      <xi:include href="xml/champlain-custom-marker.xml"/>
+    </chapter>
+    <chapter>
+      <title>Locations</title>
+      <xi:include href="xml/champlain-location.xml"/>
+      <xi:include href="xml/champlain-coordinate.xml"/>
     </chapter>
   </part>
   <part>
diff --git a/docs/reference/libchamplain-sections.txt b/docs/reference/libchamplain-sections.txt
index 122a5c6..0706bce 100644
--- a/docs/reference/libchamplain-sections.txt
+++ b/docs/reference/libchamplain-sections.txt
@@ -91,9 +91,6 @@ ChamplainLabelPrivate
 <FILE>champlain-marker</FILE>
 <TITLE>ChamplainMarker</TITLE>
 ChamplainMarker
-champlain_marker_set_position
-champlain_marker_get_latitude
-champlain_marker_get_longitude
 champlain_marker_set_selectable
 champlain_marker_get_selectable
 champlain_marker_set_draggable
@@ -314,7 +311,6 @@ champlain_marker_layer_new_full
 champlain_marker_layer_add_marker
 champlain_marker_layer_remove_marker
 champlain_marker_layer_remove_all
-champlain_marker_layer_insert_marker
 champlain_marker_layer_get_markers
 champlain_marker_layer_animate_in_all_markers
 champlain_marker_layer_animate_out_all_markers
@@ -327,18 +323,6 @@ champlain_marker_layer_unselect_all_markers
 champlain_marker_layer_set_selection_mode
 champlain_marker_layer_get_selection_mode
 champlain_marker_layer_get_bounding_box
-champlain_marker_layer_get_path_fill_color
-champlain_marker_layer_set_path_fill_color
-champlain_marker_layer_get_path_stroke_color
-champlain_marker_layer_set_path_stroke_color
-champlain_marker_layer_get_path_fill
-champlain_marker_layer_set_path_fill
-champlain_marker_layer_get_path_stroke
-champlain_marker_layer_set_path_stroke
-champlain_marker_layer_get_path_stroke_width
-champlain_marker_layer_set_path_stroke_width
-champlain_marker_layer_get_path_visible
-champlain_marker_layer_set_path_visible
 <SUBSECTION Standard>
 CHAMPLAIN_MARKER_LAYER
 CHAMPLAIN_IS_MARKER_LAYER
@@ -728,3 +712,73 @@ CHAMPLAIN_CUSTOM_MARKER_GET_CLASS
 ChamplainCustomMarkerClass
 ChamplainCustomMarkerPrivate
 </SECTION>
+
+<SECTION>
+<FILE>champlain-path-layer</FILE>
+<TITLE>ChamplainPathLayer</TITLE>
+ChamplainPathLayer
+champlain_path_layer_new
+champlain_path_layer_add_node
+champlain_path_layer_remove_node
+champlain_path_layer_remove_all
+champlain_path_layer_insert_node
+champlain_path_layer_get_nodes
+champlain_path_layer_get_bounding_box
+champlain_path_layer_get_fill_color
+champlain_path_layer_set_fill_color
+champlain_path_layer_get_stroke_color
+champlain_path_layer_set_stroke_color
+champlain_path_layer_get_fill
+champlain_path_layer_set_fill
+champlain_path_layer_get_stroke
+champlain_path_layer_set_stroke
+champlain_path_layer_get_stroke_width
+champlain_path_layer_set_stroke_width
+champlain_path_layer_get_visible
+champlain_path_layer_set_visible
+<SUBSECTION Standard>
+CHAMPLAIN_PATH_LAYER
+CHAMPLAIN_IS_PATH_LAYER
+CHAMPLAIN_TYPE_PATH_LAYER
+champlain_path_layer_get_type
+CHAMPLAIN_PATH_LAYER_CLASS
+CHAMPLAIN_IS_PATH_LAYER_CLASS
+CHAMPLAIN_PATH_LAYER_GET_CLASS
+<SUBSECTION Private>
+ChamplainPathLayerClass
+ChamplainPathLayerPrivate
+</SECTION>
+
+<SECTION>
+<FILE>champlain-coordinate</FILE>
+<TITLE>ChamplainCoordinate</TITLE>
+ChamplainCoordinate
+champlain_coordinate_new
+champlain_coordinate_new_full
+<SUBSECTION Standard>
+CHAMPLAIN_COORDINATE
+CHAMPLAIN_IS_COORDINATE
+CHAMPLAIN_TYPE_COORDINATE
+champlain_coordinate_get_type
+CHAMPLAIN_COORDINATE_CLASS
+CHAMPLAIN_IS_COORDINATE_CLASS
+CHAMPLAIN_COORDINATE_GET_CLASS
+<SUBSECTION Private>
+ChamplainCoordinateClass
+ChamplainCoordinatePrivate
+</SECTION>
+
+<SECTION>
+<FILE>champlain-location</FILE>
+<TITLE>ChamplainLocation</TITLE>
+ChamplainLocationIface
+champlain_location_set_position
+champlain_location_get_latitude
+champlain_location_get_longitude
+<SUBSECTION Standard>
+CHAMPLAIN_LOCATION
+CHAMPLAIN_IS_LOCATION
+CHAMPLAIN_TYPE_LOCATION
+champlain_location_get_type
+CHAMPLAIN_LOCATION_GET_IFACE
+</SECTION>
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]