MapWidget: Start to add proper gtk-doc documentation comments

diff --git a/libs/libgtkmap/gtkmap.c b/libs/libgtkmap/gtkmap.c
index 7dc5c6dc3c2a71d4723af02430becb85736fdbe0..d316ffa144c4fb2af451f737b7893a334a8fdb1d 100644 (file)
--- a/libs/libgtkmap/gtkmap.c
+++ b/libs/libgtkmap/gtkmap.c
@@ -17,6 +17,18 @@
  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
 
+
+/**
+ * SECTION:gtk_map
+ * @short_description: A tile based map display widget
+ * @stability: unstable
+ * 
+ * #GtkMap is simple map widget for displaying bitmap tile (256x256) based maps.
+ * 
+ *
+ */
+
+
 #include "config.h"
 
 #include <stdlib.h>
@@ -326,6 +338,15 @@ static guint gtk_map_signals[LAST_SIGNAL] = { 0 };
 
 /******************************************************************************/
 
+/**
+ * latlon2unit:
+ * @lat: Latitude to convert
+ * @lon: Longitude to convert
+ * @unitx: Pointer to result unit x
+ * @unity: Pointer to result unit y
+ *
+ * Helper function to convert from given lat,lon to map unit coordinates.
+ */
 void 
 latlon2unit(gdouble lat, gdouble lon, guint *unitx, guint *unity) 
 {
@@ -336,6 +357,16 @@ tmp=sin(lat * (M_PIl / 180.f));
 *unity=lrint((GTK_MAP_WORLD_SIZE_UNITS / MERCATOR_SPAN) * (log((1.f + tmp) / (1.f - tmp)) * 0.5f - MERCATOR_TOP));
 }
 
+/**
+ * unit2latlon:
+ * @unitx: unit x to convert
+ * @unity: unit y to convert
+ * @lat: Pointer to Latitude result
+ * @lon: Pointer to Longitude result
+ *
+ * Helper to convert from given map unit coordinates back to real lat,lon.
+ */
+
 void 
 unit2latlon(guint unitx, guint unity, gdouble *lat, gdouble *lon) 
 {
@@ -1044,6 +1075,11 @@ if (path->type==PATH_TYPE_ROUTE)
 #endif
 }
 
+/**
+ * gtk_map_set_path_display:
+ *
+ * Set displaying option for different path types.
+ */
 void
 gtk_map_set_path_display(GtkWidget *widget, gint path_mask)
 {
@@ -1081,6 +1117,12 @@ for (iter=priv->paths; iter!=NULL; iter=iter->next) {
 }
 }
 
+/**
+ * gtk_map_add_path:
+ * @path: A path object to add to the map
+ *
+ * Adds a new path to the map.
+ */
 gboolean
 gtk_map_add_path(GtkWidget *widget, Path *path)
 {
@@ -1101,6 +1143,12 @@ priv->paths=g_slist_append(priv->paths, path);
 return TRUE;
 }
 
+/**
+ * gtk_map_remove_path:
+ * @path: A paths to remove that has been previously added to the map
+ *
+ * Remove given path object from the map.
+ */
 gboolean
 gtk_map_remove_path(GtkWidget *widget, Path *path)
 {
@@ -1666,6 +1714,13 @@ if (se==0) {
 return pixbuf;
 }
 
+/**
+ * gtk_map_set_tile_repository:
+ *
+ * Set the map bitmap tile repository object to use. The map does not in itself
+ * handle downloading of loading of bitmaps. The repository object does that.
+ *
+ */
 void 
 gtk_map_set_tile_repository(GtkWidget *widget, RepoData *rd)
 {
@@ -1741,6 +1796,14 @@ return TRUE;
 
 /******************************************************************************/
 
+/**
+ * gtk_map_set_center_mode:
+ * @mode: Centering mode
+ *
+ * Set how and where the map will center itself. Default mode is CENTER_MANUAL.
+ * CENTER_LATLON will center exactly on the current track tail.
+ * A track must be active to use any other mode than CENTER_MANUAL.
+ */
 gboolean
 gtk_map_set_center_mode(GtkWidget *widget, GtkMapCenterMode mode)
 {
@@ -1775,6 +1838,13 @@ if (priv->current_track) {
 
 }
 
+/**
+ * gtk_map_set_center:
+ * @unitx: Map unit x to center on
+ * @unity: Map unit y to center on
+ *
+ * Center the map view on given map unit coordinates.
+ */
 void
 gtk_map_set_center(GtkWidget *widget, guint unitx, guint unity)
 {
@@ -1867,6 +1937,13 @@ gtk_map_refresh(widget);
 g_signal_emit(widget, gtk_map_signals[MAP_LOCATION_CHANGED], 0, priv->zoom);
 }
 
+/**
+ * gtk_map_set_center_latlon:
+ * @lat: Latitude to center on
+ * @lon: Longitude to center on
+ * 
+ * Centers map view on given lat,lon
+ */
 void
 gtk_map_set_center_latlon(GtkWidget *widget, gdouble lat, gdouble lon)
 {
@@ -1877,6 +1954,13 @@ latlon2unit(lat, lon, &unitx, &unity);
 gtk_map_set_center(widget, unitx, unity);
 }
 
+/**
+ * gtk_map_get_center_latlon:
+ * @lat: Pointer to result
+ * @lon: Pointer to result
+ *
+ * Get the current map view center point in lat,lon
+ */
 void
 gtk_map_get_center_latlon(GtkWidget *widget, gdouble *lat, gdouble *lon)
 {
@@ -1890,6 +1974,13 @@ priv=GTK_MAP_GET_PRIVATE(map);
 unit2latlon(priv->center.unitx, priv->center.unity, lat, lon);
 }
 
+/**
+ * gtk_map_pan:
+ * @delta_x:
+ * @delta_y:
+ * 
+ * Pan map view using the given deltas.
+ */
 void
 gtk_map_pan(GtkWidget *widget, gint delta_x, gint delta_y)
 {
@@ -1904,6 +1995,16 @@ priv->center_mode=CENTER_MANUAL;
 gtk_map_set_center(widget, priv->center.unitx + delta_x*GTK_MAP_PAN_UNITS, priv->center.unity + delta_y*GTK_MAP_PAN_UNITS);
 }
 
+/**
+ * gtk_map_rotate:
+ * @angle: The angle, in degress, to rotate the map view.
+ *
+ * Only available if build with cairo support!
+ *
+ * Rotates the map view around the current center point.
+ *
+ * Returns TRUE if rotation was possible, otherwise FALSE.
+ */
 gboolean 
 gtk_map_rotate(GtkWidget *widget, gfloat angle)
 {
@@ -1928,6 +2029,11 @@ return FALSE;
 #endif
 }
 
+/**
+ * gtk_map_refresh:
+ *
+ * Force a redraw of the map view.
+ */
 void
 gtk_map_refresh(GtkWidget *widget)
 {
@@ -2053,6 +2159,14 @@ return FALSE;
 
 /******************************************************************************/
 
+/**
+ * gtk_map_set_context_menu:
+ * @menu: A #GtkMenu to add as context menu
+ *
+ * Add a context menu to display when the map is clicked on with the right mouse button.
+ * On hildon build the context menu is set with gtk_widget_tap_and_hold_setup().
+ *
+ */
 void
 gtk_map_set_context_menu(GtkWidget *widget, GtkMenu *menu)
 {
@@ -2091,6 +2205,11 @@ g_object_unref(priv->menu);
 priv->menu=NULL;
 }
 
+/**
+ * gtk_map_get_menu_latlon:
+ *
+ * Get the lat, lon coordinates from where the mouse was clicked to get the context menu.
+ */
 void
 gtk_map_get_menu_latlon(GtkWidget *widget, gdouble *lat, gdouble *lon)
 {