[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]