Merge pull request #42 from mvglasow/docR6361

Refactor:gui_internal:More documentation

3 files changed, 62 insertions, 31 deletions

diff --git a/navit/gui/internal/gui_internal_keyboard.c b/navit/gui/internal/gui_internal_keyboard.c
index c01eff690..509cc5ed4 100644
--- a/navit/gui/internal/gui_internal_keyboard.c
+++ b/navit/gui/internal/gui_internal_keyboard.c
@@ -111,6 +111,8 @@ struct gui_internal_keyb_mode {
  * new keyboard widget
  * @param mode The new keyboard mode, see {@link gui_internal_keyboard(struct gui_priv *, struct widget *, int)}
  * for a description of possible values
+ *
+ * @return {@code wkbdb} if a non-NULL value was passed, else a new keyboard widget will be returned.
  */
 struct widget *
 gui_internal_keyboard_do(struct gui_priv *this, struct widget *wkbdb, int mode)
diff --git a/navit/gui/internal/gui_internal_priv.h b/navit/gui/internal/gui_internal_priv.h
index 49bab2c70..0dee59db2 100644
--- a/navit/gui/internal/gui_internal_priv.h
+++ b/navit/gui/internal/gui_internal_priv.h
@@ -35,11 +35,11 @@ struct route_data {
   int route_showing;
 };
 
-//##############################################################################################################
-//# Description:
-//# Comment:
-//# Authors: Martin Schaller (04/2008)
-//##############################################################################################################
+/**
+ * Private data for the internal GUI.
+ *
+ * @author Martin Schaller (04/2008)
+ */
 struct gui_priv {
 	struct navit *nav;
 	struct attr self;
@@ -57,19 +57,11 @@ struct gui_priv {
 	char *font_name;
 	int fullscreen;
 	struct graphics_font *fonts[3];
-	/**
-	 * The size (in pixels) that xs style icons should be scaled to.
-	 * This icon size can be too small to click it on some devices.
-	 */
-	int icon_xs;
-	/**
-	 * The size (in pixels) that s style icons (small) should be scaled to
-	 */
-	int icon_s;
-	/**
-	 * The size (in pixels) that l style icons should be scaled to
-	 */
-	int icon_l;
+	int icon_xs;						/**< The size (in pixels) that xs style icons should be scaled to.
+										  *  This icon size can be too small to click it on some devices.
+										  */
+	int icon_s;							/**< The size (in pixels) that s style icons (small) should be scaled to */
+	int icon_l;							/**< The size (in pixels) that l style icons should be scaled to */
 	int pressed;
 	struct widget *widgets;
 	int widgets_count;
@@ -86,30 +78,29 @@ struct gui_priv {
 	int signal_on_map_click;
 	char *country_iso2;
 	int speech;
-	int keyboard;
-	int keyboard_required;
-	/**
-	 * The setting information read from the configuration file.
-	 * values of -1 indicate no value was specified in the config file.
-	 */
-	struct gui_config_settings config;
+	int keyboard;						/**< Whether the internal GUI keyboard is enabled */
+	int keyboard_required;				/**< Whether keyboard input is needed. This is only used by the
+										  *  HTML menu, text entry dialogs do not use this member.
+										  */
+	struct gui_config_settings config;	/**< The setting information read from the configuration file.
+										  *  values of -1 indicate no value was specified in the config file.
+										  */
 	struct event_idle *idle;
 	struct callback *motion_cb,*button_cb,*resize_cb,*keypress_cb,*window_closed_cb,*idle_cb, *motion_timeout_callback;
 	struct event_timeout *motion_timeout_event;
 	struct point current;
 
 	struct callback * vehicle_cb;
-	  /**
-	   * Stores information about the route.
-	   */
-	struct route_data route_data;
+	struct route_data route_data;		/**< Stores information about the route. */
 
 	struct gui_internal_data data;
 	struct callback_list *cbl;
 	int flags;
 	int cols;
-	struct attr osd_configuration;
-	int pitch;
+	struct attr osd_configuration;		/**< The OSD configuration, a set of flags controlling which OSD
+	                                      *  items will be visible.
+	                                      */
+	int pitch;							/**< The pitch for the 3D map view. */
 	int flags_town,flags_street,flags_house_number;
 	int radius;
 	int mouse_button_clicked_on_map;
diff --git a/navit/gui/internal/gui_internal_widget.c b/navit/gui/internal/gui_internal_widget.c
index 8a72587d6..0db2ce4fa 100644
--- a/navit/gui/internal/gui_internal_widget.c
+++ b/navit/gui/internal/gui_internal_widget.c
@@ -653,6 +653,12 @@ gui_internal_widget_reset_pack(struct gui_priv *this, struct widget *w)
 	}
 }
 
+/**
+ * @brief Adds a child widget to a parent widget, making it the last child.
+ *
+ * @param parent The parent widget
+ * @param child The child widget
+ */
 void
 gui_internal_widget_append(struct widget *parent, struct widget *child)
 {
@@ -664,6 +670,12 @@ gui_internal_widget_append(struct widget *parent, struct widget *child)
 	child->parent=parent;
 }
 
+/**
+ * @brief Adds a child widget to a parent widget, making it the first child.
+ *
+ * @param parent The parent widget
+ * @param child The child widget
+ */
 void
 gui_internal_widget_prepend(struct widget *parent, struct widget *child)
 {
@@ -673,6 +685,15 @@ gui_internal_widget_prepend(struct widget *parent, struct widget *child)
 	child->parent=parent;
 }
 
+/**
+ * @brief Adds a child widget to a parent widget.
+ *
+ * Placement of the child widget among its siblings depends on the comparison function {@code func}.
+ *
+ * @param parent The parent widget
+ * @param child The child widget
+ * @param func The comparison function
+ */
 void
 gui_internal_widget_insert_sorted(struct widget *parent, struct widget *child, GCompareFunc func)
 {
@@ -684,6 +705,14 @@ gui_internal_widget_insert_sorted(struct widget *parent, struct widget *child, G
 }
 
 
+/**
+ * @brief Destroys all child widgets.
+ *
+ * This function is recursive, destroying all widgets in the child hierarchy of {@code w}.
+ *
+ * @param this The internal GUI instance
+ * @param w The widget whose children are to be destroyed
+ */
 void
 gui_internal_widget_children_destroy(struct gui_priv *this, struct widget *w)
 {
@@ -701,6 +730,15 @@ gui_internal_widget_children_destroy(struct gui_priv *this, struct widget *w)
 }
 
 
+/**
+ * @brief Destroys a widget.
+ *
+ * This function also takes care of recursively destroying the entire child widget hierarchy of
+ * {@code w} prior to destroying {@code w} itself.
+ *
+ * @param this The internal GUI instance
+ * @param w The widget to destroy
+ */
 void
 gui_internal_widget_destroy(struct gui_priv *this, struct widget *w)
 {