Merge branch 'trunk' into osd-status

6 files changed, 394 insertions, 72 deletions

diff --git a/navit/android/src/org/navitproject/navit/NavitVehicle.java b/navit/android/src/org/navitproject/navit/NavitVehicle.java
index e42a18470..313502b96 100644
--- a/navit/android/src/org/navitproject/navit/NavitVehicle.java
+++ b/navit/android/src/org/navitproject/navit/NavitVehicle.java
@@ -19,6 +19,8 @@
 
 package org.navitproject.navit;
 
+import java.util.List;
+
 import android.content.BroadcastReceiver;
 import android.content.Context;
 import android.content.Intent;
@@ -148,10 +150,23 @@ public class NavitVehicle {
 		sLocationManager.requestLocationUpdates(preciseProvider, 0, 0, preciseLocationListener);
 		sLocationManager.addGpsStatusListener(preciseLocationListener);
 
-		// If the 2 providers are the same, only activate one listener
+		/*
+		 * Since Android criteria have no way to specify "fast fix", lowCriteria may return the same
+		 * provider as highCriteria, even if others are available. In this case, do not register two
+		 * listeners for the same provider but pick the fast provider manually. (Usually there will
+		 * only be two providers in total, which makes the choice easy.)
+		 */
 		if (fastProvider == null || preciseProvider.compareTo(fastProvider) == 0) {
+			List<String> fastProviderList = sLocationManager.getProviders(lowCriteria, false);
 			fastProvider = null;
-		} else {
+			for (String fastCandidate: fastProviderList) {
+				if (preciseProvider.compareTo(fastCandidate) != 0) {
+					fastProvider = fastCandidate;
+					break;
+				}
+			}
+		}
+		if (fastProvider != null) {
 			sLocationManager.requestLocationUpdates(fastProvider, 0, 0, fastLocationListener);
 		}
 	}
diff --git a/navit/command.c b/navit/command.c
index 812abbc90..7ebfda4f5 100644
--- a/navit/command.c
+++ b/navit/command.c
@@ -28,14 +28,26 @@ osd[@type=="xxx"].active=0;osd[@type=="yyy"].active=0
 */
 
 
+/**
+ * The result, or interim result, of evaluating a saved command.
+ */
 struct result {
-	struct attr attr;
+	struct attr attr;	/**< The attribute. If {@code allocated} is true, it stores an object that was
+						 *   successfully retrieved. Else it is either a placeholder or a constant value.
+						 */
 	double val;
-	const char *var;
-	int varlen;
-	const char *attrn;
-	int attrnlen;
-	int allocated;
+	const char *var;	/**< If {@code allocated} is false, the name of the object to be resolved.
+						 *   Else, it is the name of the object successfully retrieved and stored in
+						 *   {@code attr}, or {@code NULL} if retrieval failed.
+						 *   Only the first {@code varlen} characters are significant.
+						 */
+	int varlen;			/**< Number of significant characters in {@code var} */
+	const char *attrn;	/**< The name of an object that has been resolved but not yet retrieved,
+						 *   {@code NULL} otherwise. Only the first {@code attrnlen} characters are
+						 *   significant.
+						 */
+	int attrnlen;		/**< Number of significant characters in {@code attrn} */
+	int allocated;		/**< Whether the result has been calculated */
 };
 
 struct result_list {
@@ -50,11 +62,17 @@ struct context {
 	struct result res;
 };
 
+/**
+ * Information about a callback function for a saved command.
+ */
 struct command_saved_cb {
-	struct callback *cb;
+	struct callback *cb;	/**< The callback function */
 	struct attr attr;
 };
 
+/**
+ * A saved command.
+ */
 struct command_saved {
 	struct context ctx;
 	struct result res;
@@ -63,8 +81,10 @@ struct command_saved {
 	struct callback *idle_cb;
 	struct callback *register_cb;			/**< Callback to register all the callbacks **/
 	struct event_idle *register_ev;		/**< Idle event to register all the callbacks **/
-	struct attr context_attr;
-	int num_cbs;
+	struct attr context_attr;			/**< The root of the object hierarchy, which will be assumed as
+										 *   the parent of all unqualified or partially qualified object
+										 *   references. **/
+	int num_cbs;						/**< Number of entries in {@code cbs} **/
 	struct command_saved_cb *cbs;		/**< List of callbacks for this saved command **/
 	struct callback *cb; /**< Callback that should be called when we re-evaluate **/
 	int error;
@@ -212,6 +232,21 @@ command_attr_type(struct result *res)
 	return attr_from_name(attrn);
 }
 
+/**
+ * @brief Retrieves an attribute from an object.
+ *
+ * This function will retrieve the first matching attribute by calling the {@code get_attr} method for
+ * the object type. If {@code object} does not refer to a valid object, or the {@code get_attr} method
+ * for the object type could not be defined, the function fails and zero is returned.
+ *
+ * @param ctx The context (ignored)
+ * @param object The object for which the attribute is to be retrieved.
+ * @param attr_type The type of attribute to retrieve
+ * @param ret Points to a {@code struct attr} to which the attribute will be copied
+ *
+ * @return True if a matching attribute was found, false if no matching attribute was found or an error
+ * occurred
+ */
 static int
 command_object_get_attr(struct context *ctx, struct attr *object, enum attr_type attr_type, struct attr *ret)
 {
@@ -245,12 +280,34 @@ command_object_remove_attr(struct context *ctx, struct attr *object, struct attr
 }
 
 
+/**
+ * @brief Retrieves the current value of an attribute and stores it in {@code res}.
+ *
+ * If {@code ctx->skip} is true, the function aborts and no action is taken.
+ *
+ * Before calling this function, object references in {@code res} must be resolved. That is,
+ * {@code res->attr} holds a copy of {@code ctx->attr} and the first {@code res->attrnlen} characters of
+ * {@code res->attrn} correspond to the object name.
+ *
+ * After this function completes, {@code res->allocated} is true, and {@code res->attrn} and
+ * {@code res->attrnlen} are reset.
+ *
+ * If the attribute was successfully retrieved, the first {@code res->varlen} characters of
+ * {@code res->var} correspond to an object name and {@code res->attr} holds the attribute.
+ *
+ * If the attribute could not be retrieved, {@code res->attr.type} is set to {@code attr_none}, and
+ * {@code res->var} and {@code res->varlen} are reset.
+ *
+ * @param ctx The context
+ * @param res The result
+ */
 static void
 command_get_attr(struct context *ctx, struct result *res)
 {
 	int result;
 	struct result tmp={{0,},};
 	enum attr_type attr_type=command_attr_type(res);
+	enum attr_type parent_type = res->attr.type; /* for debugging only */
 	if (ctx->skip)
 		return;
 	result=command_object_get_attr(ctx, &res->attr, attr_type, &tmp.attr);
@@ -258,9 +315,11 @@ command_get_attr(struct context *ctx, struct result *res)
 	*res=tmp;
 	res->allocated=1;
 	if (result) {
+		dbg(lvl_debug, "successfully retrieved '%s' from '%s'\n", attr_to_name(attr_type), attr_to_name(parent_type));
 		res->var=res->attrn;
 		res->varlen=res->attrnlen;
 	} else {
+		dbg(lvl_warning, "could not retrieve '%s' from '%s'\n", attr_to_name(attr_type), attr_to_name(parent_type));
 		result_free(res);
 		res->attr.type=attr_none;
 		res->var=NULL;
@@ -296,6 +355,20 @@ command_set_attr(struct context *ctx, struct result *res, struct result *newres)
 	*res=*newres;
 }
 
+/**
+ * @brief Resolves an object reference.
+ *
+ * Prior to calling this function, {@code res} must contain a valid, unresolved object reference:
+ * {@code res->attr.type} must be {@code attr_none}, and the first {@code res->varlen} characters of
+ * {@code res->var} must correspond to an object name.
+ *
+ * After the function returns, {@code res->attr} holds a copy of {@code ctx->attr} and the first
+ * {@code res->attrnlen} characters of {@code res->attrn} correspond to the object name.
+ * {@code res->var} and {@code res->varlen} are reset.
+ *
+ * @param ctx The context
+ * @param res The result
+ */
 static void
 resolve_object(struct context *ctx, struct result *res)
 {
@@ -308,6 +381,24 @@ resolve_object(struct context *ctx, struct result *res)
 	}
 }
 
+/**
+ * @brief Resolves and retrieves an object and stores it in {@code res}.
+ *
+ * Prior to calling this function, {@code res} must contain a valid, unresolved object reference:
+ * {@code res->attr.type} must be {@code attr_none}, and the first {@code res->varlen} characters of
+ * {@code res->var} must correspond to an object name.
+ *
+ * If {@code ctx->skip} is true, the object reference will be resolved but the object will not be
+ * retrieved: the first {@code res->attrnlen} characters of {@code res->attrn} correspond to the object
+ * name after the function returns, while {@code res->var} and {@code res->varlen} are reset.
+ *
+ * If {@code ctx->skip} is false, {@code res->allocated} is true after this function completes. The
+ * object is stored in {@code res->attr} if it was successfully retrieved, otherwise {@code res->var}
+ * and {@code res->varlen} are reset.
+ *
+ * @param ctx The context
+ * @param res The result
+ */
 static void
 resolve(struct context *ctx, struct result *res)
 {
@@ -567,13 +658,42 @@ result_set(struct context *ctx, enum set_type set_type, const char *op, int len,
 	ctx->error=internal;
 }
 
+/**
+ * @brief Evaluates a value and stores its result.
+ *
+ * This function evaluates the first value in {@code ctx->expr}. A value can be either an object name
+ * (such as {@code vehicle.position_speed}) or a literal value.
+ *
+ * If evaluation is successful, the result is stored in {@code res->attr}.
+ *
+ * If an object name is encountered, the result has an attribute type of {@code attr_none} and the first
+ * {@code res->varlen} characters of {@code res->var} will point to the object name.
+ *
+ * If a literal value is encountered, the result's attribute type is set to the corresponding generic
+ * data type and its value is stored with the attribute.
+ *
+ * After this function returns, {@code ctx->expr} contains the rest of the expression string, which was
+ * not evaluated. Leading spaces before the value will be discarded with the value.
+ *
+ * If {@code ctx->expr}, after eliminating any leading whitespace, does not begin with a valid value,
+ * one of the following errors is stored in {@code ctx->error}:
+ * <ul>
+ * <li>{@code illegal_number_format} An illegal number format, such as a second decimal dot, was
+ * encountered.</li>
+ * <li>{@code missing_double_quote} A double quote without a matching second double quote was found.</li>
+ * <li>{@code eof_reached} The expression string is empty.</li>
+ * <li>{@code illegal_character} The expression string begins with a character which is illegal in a
+ * value. This may happen when the expression string begins with an operator.</li>
+ * </ul>
+ *
+ * @param ctx The context to evaluate
+ * @param res Points to a {@code struct res} in which the result will be stored
+ */
 static void
 eval_value(struct context *ctx, struct result *res) {
 	const char *op;
 	int dots=0;
 
-	op=ctx->expr;
-
 	result_free(res);
 
 	res->varlen=0;
@@ -581,9 +701,11 @@ eval_value(struct context *ctx, struct result *res) {
 	res->attrnlen=0;
 	res->attrn=NULL;
 
-	while (g_ascii_isspace(*op)) {
-		op++;
+	while (g_ascii_isspace(*(ctx->expr))) {
+		ctx->expr++;
 	}
+	op = ctx->expr;
+
 	if ((op[0] >= 'a' && op[0] <= 'z') || (op[0] >= 'A' && op[0] <= 'Z') || op[0] == '_') {
 		const char *s=op;
 		for (;;) {
@@ -650,11 +772,37 @@ eval_value(struct context *ctx, struct result *res) {
 	if (!*op)
 		ctx->error=eof_reached;
 	else {
-		dbg(lvl_error,"illegal character 0x%x\n",*op);
+		/*
+		 * If we get here, ctx->expr does not begin with a variable or a literal value. This is not an
+		 * error if this function is being called to test if an expression begins with a value.
+		 */
+		dbg(lvl_debug, "character 0x%x is illegal in a value\n",*op);
 		ctx->error=illegal_character;
 	}
 }
 
+/**
+ * @brief Retrieves the next object reference from an expression.
+ *
+ * This function scans the expression string {@code ctx->expr} for the next object reference. Anything
+ * other than an object reference (whitespace characters, literal values, operators and even illegal
+ * characters) is discarded until either the end of the string is reached or an object reference is
+ * encountered.
+ *
+ * After this function completes successfully, {@code res->attr.type} is {@code attr_none} and the first
+ * {@code res->varlen} characters of {@code res->var} point to the object name.
+ *
+ * Object names retrieved by this function are unqualified, i.e. {@code vehicle.position_speed} will be
+ * retrieved as {@code vehicle} on the first call (return value 2) and {@code position_speed} on the
+ * second call (return value 1).
+ *
+ * @param ctx The context
+ * @param res Points to a {@code struct result} where the result will be stored.
+ *
+ * @return If a complete object name has been retrieved, the return value is 1. If a partial object name
+ * has been retrieved (e.g. {@code vehicle} from {@code vehicle.position_speed}), the return value is 2.
+ * If no object references were found, the return value is 0.
+ */
 static int
 get_next_object(struct context *ctx, struct result *res) {
 	
@@ -1495,9 +1643,20 @@ command_saved_error (struct command_saved *cs)
 	return cs->error;
 }
 
+/**
+ * @brief Idle function to evaluate a command
+ *
+ * This function is called from an idle loop for asynchronous evaluation but may also be called in-line.
+ *
+ * The result of the evaluation can be retrieved from {@code cs->res} after this function returns. If an
+ * error occurred, it will be stored in {@code cs->error}.
+ *
+ * @param cs The command to evaluate
+ */
 static void
 command_saved_evaluate_idle (struct command_saved *cs) 
 {
+	dbg(lvl_debug, "enter: cs=%p, cs->command=%s\n", cs, cs->command);
 	// Only run once at a time
 	if (cs->idle_ev) {
 		event_remove_idle(cs->idle_ev);
@@ -1517,9 +1676,21 @@ command_saved_evaluate_idle (struct command_saved *cs)
 	}
 }
 
+/**
+ * @brief Evaluates a command
+ *
+ * This function examines {@code cs->async} to determine if the command should be evaluated immediately.
+ * If {@code cs->async} is true, an idle event is registered to register the command. Else the command
+ * is evaluated immediately and the result can be retrieved immediately after this function returns.
+ *
+ * See {@link command_saved_evaluate_idle(struct command_saved *)} for details.
+ *
+ * @param cs The command to evaluate
+ */
 static void
 command_saved_evaluate(struct command_saved *cs)
 {	
+	dbg(lvl_debug, "enter: cs=%p, cs->async=%d, cs->command=%s\n", cs, cs->async, cs->command);
 	if (!cs->async) {
 		command_saved_evaluate_idle(cs);
 		return;
@@ -1536,6 +1707,11 @@ command_saved_evaluate(struct command_saved *cs)
 	cs->idle_ev = event_add_idle(100, cs->idle_cb);
 }
 
+/**
+ * @brief Recreates all callbacks for a saved command
+ *
+ * @param cs The saved command
+ */
 static void
 command_saved_callbacks_changed(struct command_saved *cs)
 {
@@ -1544,6 +1720,8 @@ command_saved_callbacks_changed(struct command_saved *cs)
 	struct object_func *func;
 	struct attr attr;
 
+	dbg(lvl_debug, "enter: cs=%p, cs->async=%d, cs->command=%s\n", cs, cs->async, cs->command);
+
 	if (cs->register_ev) {
 		event_remove_idle(cs->register_ev);
 		cs->register_ev = NULL;
@@ -1573,24 +1751,52 @@ command_saved_callbacks_changed(struct command_saved *cs)
 	command_register_callbacks(cs);
 }
 
+/**
+ * @brief Registers callbacks for a saved command
+ *
+ * This function registers callbacks for each attribute used in a saved command, causing the command to
+ * be re-evaluated whenever its value might change.
+ *
+ * This function will fail if an object used in the expression could not be resolved. This may happen
+ * during startup if this function is called before all objects have been created. In this case, the
+ * caller should schedule the function to be called again at a later time.
+ *
+ * It will also fail if an error is encountered. This can be determined by examining
+ * {@code cs->ctx.error} after the function returns.
+ *
+ * @param cs The command
+ *
+ * @return True if all callbacks were successfully registered, false if the function failed
+ */
 static int
 command_register_callbacks(struct command_saved *cs)
 {
-	struct attr prev,cb_attr,attr;
+	struct attr prev;	/* The parent of the next object which will be retrieved. */
+	struct attr cb_attr;
 	int status;
 	struct object_func *func;
 	struct callback *cb;
+	int tmpoffset;	/* For debugging. Because we work with pointers into the same string instance.
+					 * we can figure out offsets by using simple pointer arithmetics.
+					 */
 	
-	attr = cs->context_attr;
+	dbg(lvl_debug, "enter: cs=%p, cs->async=%d, cs->command=%s\n", cs, cs->async, cs->command);
 	cs->ctx.expr = cs->command;
-	cs->ctx.attr = &attr;
 	prev = cs->context_attr;
 
 	while ((status = get_next_object(&cs->ctx, &cs->res)) != 0) {
+		tmpoffset = cs->res.var - cs->command;
+		cs->ctx.attr = &prev;
 		resolve(&cs->ctx, &cs->res);
 
-		if (cs->ctx.error || (cs->res.attr.type == attr_none)) {
-			// We could not resolve an object, perhaps because it has not been created
+		if (cs->ctx.error) {
+			/* An error occurred while parsing the command */
+			tmpoffset = cs->ctx.expr - cs->command;
+			dbg(lvl_error, "parsing error: cs=%p, cs->ctx.error=%d\n\t%s\n\t%*s\n", cs, cs->ctx.error, cs->command, tmpoffset + 1, "^");
+			return 0;
+		} else if (cs->res.attr.type == attr_none) {
+			/* We could not resolve an object, perhaps because it has not been created */
+			dbg(lvl_error, "could not resolve object in cs=%p:\n\t%s\n\t%*s\n", cs, cs->command, tmpoffset + 1, "^");
 			return 0;
 		}
 
@@ -1600,7 +1806,6 @@ command_register_callbacks(struct command_saved *cs)
 			if (func->add_attr) {
 				if (status == 2) { // This is not the final attribute name
 					cb = callback_new_attr_1(callback_cast(command_saved_callbacks_changed), cs->res.attr.type, (void*)cs);
-					attr = cs->res.attr;
 				} else if (status == 1) { // This is the final attribute name
 					cb = callback_new_attr_1(callback_cast(command_saved_evaluate), cs->res.attr.type, (void*)cs);
 					cs->ctx.attr = &cs->context_attr;
@@ -1619,7 +1824,7 @@ command_register_callbacks(struct command_saved *cs)
 				func->add_attr(prev.u.data, &cb_attr);
 
 			} else {
-				dbg(lvl_error, "Could not add callback because add_attr is missing for type %i}n", prev.type);
+				dbg(lvl_error, "Could not add callback because add_attr is missing for type %i\n", prev.type);
 			}
 		}
 
@@ -1632,15 +1837,26 @@ command_register_callbacks(struct command_saved *cs)
 
 	command_saved_evaluate_idle(cs);
 
+	dbg(lvl_debug, "done: cs=%p, cs->command=%s\n", cs, cs->command);
 	return 1;
 }
 
+/**
+ * @brief Creates a new saved command.
+ *
+ * @param command The command string
+ * @param attr The context attribute for the saved command
+ * @param cb The callback to call whenver the command is re-evaluated
+ * @param async Whether the saved command should be flagged as asynchronous, causing it to be evaluated
+ * in an idle callback
+ */
 struct command_saved *
 command_saved_attr_new(char *command, struct attr *attr, struct callback *cb, int async)
 {
 	struct command_saved *ret;
 
 	ret = g_new0(struct command_saved, 1);
+	dbg(lvl_debug, "enter, ret=%p, command=%s\n", ret, command);
 	ret->command = g_strdup(command);
 	ret->context_attr = *attr;
 	ret->cb = cb;
@@ -1649,6 +1865,7 @@ command_saved_attr_new(char *command, struct attr *attr, struct callback *cb, in
 
 	if (!command_register_callbacks(ret)) {
 		// We try this as an idle call again
+		dbg(lvl_debug, "could not register callbacks, will retry as an idle call\n");
 		ret->register_cb = callback_new_1(callback_cast(command_saved_callbacks_changed), ret);
 		ret->register_ev = event_add_idle(300, ret->register_cb);
 	}		
diff --git a/navit/gui/internal/gui_internal.c b/navit/gui/internal/gui_internal.c
index 23d4d24c6..3f65397dc 100644
--- a/navit/gui/internal/gui_internal.c
+++ b/navit/gui/internal/gui_internal.c
@@ -1078,6 +1078,18 @@ gui_internal_cmd_delete_waypoint(struct gui_priv *this, struct widget *wm, void
 }
 
 
+/**
+ * @brief
+ *
+ * One of {@code pc_in} or {@code g_in} must be supplied, the other should be {@code NULL}.
+ *
+ * @param this The internal GUI instance
+ * @param pc_in Projected coordinates of the position
+ * @param g_in WGS84 coordinates of the position
+ * @param wm
+ * @param name The display name for the position
+ * @param flags Flags specifying the operations available from the GUI
+ */
 /* meaning of the bits in "flags":
  * 1: "Streets"
  * 2: "House numbers"
diff --git a/navit/gui/internal/gui_internal_command.c b/navit/gui/internal/gui_internal_command.c
index 2c9ac2f64..b7f561a91 100644
--- a/navit/gui/internal/gui_internal_command.c
+++ b/navit/gui/internal/gui_internal_command.c
@@ -39,6 +39,17 @@
 
 extern char *version;
 
+/**
+ * @brief Converts a WGS84 coordinate pair to its string representation.
+ *
+ * This function takes a coordinate pair with latitude and longitude in degrees and converts them to a
+ * string of the form {@code 45°28'0" N 9°11'26" E}.
+ *
+ * @param gc A WGS84 coordinate pair
+ * @param sep The separator character to insert between latitude and longitude
+ *
+ * @return The coordinates as a formatted string
+ */
 static char *
 coordinates_geo(const struct coord_geo *gc, char sep)
 {
@@ -46,6 +57,7 @@ coordinates_geo(const struct coord_geo *gc, char sep)
 	int lat_deg,lat_min,lat_sec;
 	int lng_deg,lng_min,lng_sec;
 	struct coord_geo g=*gc;
+	char *ret;
 
 	if (g.lat < 0) {
 		g.lat=-g.lat;
@@ -61,9 +73,35 @@ coordinates_geo(const struct coord_geo *gc, char sep)
 	lng_sec=fmod(g.lng*3600+0.5,60);
 	lng_min=fmod(g.lng*60-lng_sec/60.0+0.5,60);
 	lng_deg=g.lng-lng_min/60.0-lng_sec/3600.0+0.5;;
-	return g_strdup_printf("%d°%d'%d\" %c%c%d°%d'%d\" %c",lat_deg,lat_min,lat_sec,latc,sep,lng_deg,lng_min,lng_sec,lngc);
+
+	/* Don't use g_strdup_printf for the full string because it has issues with extended ANSI characters
+	 * (notably the degree sign, 0xb0) on Android Lollipop.
+	 */
+	ret = g_strjoin(NULL,
+			g_strdup_printf("%d", lat_deg), "°",
+			g_strdup_printf("%d", lat_min), "'",
+			g_strdup_printf("%d", lat_sec), "\" ",
+			g_strnfill(1, latc),
+			g_strnfill(1, sep),
+			g_strdup_printf("%d", lng_deg), "°",
+			g_strdup_printf("%d", lng_min), "'",
+			g_strdup_printf("%d", lng_sec), "\" ",
+			g_strnfill(1, lngc),
+			NULL);
+	return ret;
 }
 
+/**
+ * @brief Converts a coordinate pair to its WGS84 string representation.
+ *
+ * This function takes a coordinate pair, transforms it to WGS84 and converts it to a string of the form
+ * {@code 45°28'0" N 9°11'26" E}.
+ *
+ * @param gc A coordinate pair
+ * @param sep The separator character to insert between latitude and longitude
+ *
+ * @return The coordinates as a formatted string
+ */
 char *
 gui_internal_coordinates(struct pcoord *pc, char sep)
 {
diff --git a/navit/gui/internal/gui_internal_widget.c b/navit/gui/internal/gui_internal_widget.c
index ebd91d200..8a72587d6 100644
--- a/navit/gui/internal/gui_internal_widget.c
+++ b/navit/gui/internal/gui_internal_widget.c
@@ -108,6 +108,12 @@ gui_internal_image_render(struct gui_priv *this, struct widget *w)
 	}
 }
 
+/**
+ * @brief Renders a label.
+ *
+ * @param this The internal GUI instance
+ * @param w The widget to render
+ */
 static void
 gui_internal_label_render(struct gui_priv *this, struct widget *w)
 {
@@ -138,9 +144,15 @@ gui_internal_label_render(struct gui_priv *this, struct widget *w)
 }
 
 /**
- * @brief A text box is a widget that renders a text string containing newlines.
+ * @brief Creates a text box.
+ *
+ * A text box is a widget that renders a text string containing newlines.
  * The string will be broken up into label widgets at each newline with a vertical layout.
  *
+ * @param this The internal GUI instance
+ * @param text The text to be displayed in the text box
+ * @param font The font to use for the text
+ * @param flags
  */
 struct widget *
 gui_internal_text_font_new(struct gui_priv *this, const char *text, int font, enum flags flags)
@@ -342,9 +354,10 @@ static void gui_internal_box_render(struct gui_priv *this, struct widget *w)
 
 
 /**
- * @brief Compute the size and location for the widget.
- *
+ * @brief Computes the size and location for the widget.
  *
+ * @param this The internal GUI instance
+ * @param w The widget to render
  */
 static void gui_internal_box_pack(struct gui_priv *this, struct widget *w)
 {
@@ -366,7 +379,7 @@ static void gui_internal_box_pack(struct gui_priv *this, struct widget *w)
 	}
 
 
-	/**
+	/*
 	 * count the number of children
 	 */
 	l=w->children;
@@ -378,7 +391,7 @@ static void gui_internal_box_pack(struct gui_priv *this, struct widget *w)
 		orientation=orientation_horizontal;
 	switch (orientation) {
 	case orientation_horizontal:
-		/**
+		/*
 		 * For horizontal orientation:
 		 * pack each child and find the largest height and
 		 * compute the total width. x spacing (spx) is considered
@@ -407,7 +420,7 @@ static void gui_internal_box_pack(struct gui_priv *this, struct widget *w)
 			expandd=expand=1;
 		break;
 	case orientation_vertical:
-		/**
+		/*
 		 * For vertical layouts:
 		 * We pack each child and compute the largest width and
 		 * the total height.  y spacing (spy) is considered
@@ -436,7 +449,7 @@ static void gui_internal_box_pack(struct gui_priv *this, struct widget *w)
 			expandd=expand=1;
 		break;
 	case orientation_horizontal_vertical:
-		/**
+		/*
 		 * For horizontal_vertical orientation
 		 * pack the children.
 		 * Compute the largest height and largest width.
@@ -467,7 +480,7 @@ static void gui_internal_box_pack(struct gui_priv *this, struct widget *w)
 		expandd=expand=1;
 		break;
 	default:
-		/**
+		/*
 		 * No orientation was specified.
 		 * width and height are both 0.
 		 * The width & height of this widget
@@ -487,7 +500,7 @@ static void gui_internal_box_pack(struct gui_priv *this, struct widget *w)
 		expand=100;
 #endif
 
-	/**
+	/*
 	 * At this stage the width and height of this
 	 * widget has been computed.
 	 * We now make a second pass assigning heights,
@@ -609,7 +622,7 @@ static void gui_internal_box_pack(struct gui_priv *this, struct widget *w)
 		gui_internal_box_pack(this, w);
 		return;
 	}
-	/**
+	/*
 	 * Call pack again on each child,
 	 * the child has now had its size and coordinates
 	 * set so they can repack their children.
@@ -798,7 +811,7 @@ gui_internal_scroll_buttons_init(struct gui_priv *this, struct widget *widget, s
  *
  * @param this The graphics context.
  * @param flags widget sizing flags.
- * @returns The newly created widget
+ * @return The newly created widget
  */
 struct widget * gui_internal_widget_table_new(struct gui_priv * this, enum flags flags, int buttons)
 {
@@ -828,8 +841,12 @@ struct widget * gui_internal_widget_table_new(struct gui_priv * this, enum flags
 
 /**
  * @brief Clears all the rows from the table.
+ *
  * This function removes all rows from a table.
  * New rows can later be added to the table.
+ *
+ * @param this The internal GUI instance
+ * @param table The table widget
  */
 void gui_internal_widget_table_clear(struct gui_priv * this,struct widget * table)
 {
@@ -858,9 +875,11 @@ void gui_internal_widget_table_clear(struct gui_priv * this,struct widget * tabl
 }
 
 /**
- * @brief Move GList pointer to the next table row, skipping other table children (button box, for example).
- * @param row GList pointer into the children list 
- * @returns GList pointer to the next row in the children list, or NULL if there are no any rows left.
+ * @brief Moves GList pointer to the next table row, skipping other table children (button box, for example).
+ *
+ * @param row GList pointer into the children list
+ *
+ * @return GList pointer to the next row in the children list, or NULL if there are no any rows left.
  */
 GList *
 gui_internal_widget_table_next_row(GList * row)
@@ -873,9 +892,11 @@ gui_internal_widget_table_next_row(GList * row)
 }
 
 /**
- * @brief Move GList pointer to the previous table row, skipping other table children (button box, for example).
- * @param row GList pointer into the children list 
- * @returns GList pointer to the previous row in the children list, or NULL if there are no any rows left.
+ * @brief Moves GList pointer to the previous table row, skipping other table children (button box, for example).
+ *
+ * @param row GList pointer into the children list
+ *
+ * @return GList pointer to the previous row in the children list, or NULL if there are no any rows left.
  */
 GList *
 gui_internal_widget_table_prev_row(GList * row)
@@ -888,9 +909,11 @@ gui_internal_widget_table_prev_row(GList * row)
 }
 
 /**
- * @brief Move GList pointer to the first table row, skipping other table children (button box, for example).
- * @param row GList pointer into the children list 
- * @returns GList pointer to the first row in the children list, or NULL if table is empty.
+ * @brief Moves GList pointer to the first table row, skipping other table children (button box, for example).
+ *
+ * @param row GList pointer into the children list
+ *
+ * @return GList pointer to the first row in the children list, or NULL if table is empty.
  */
 GList *
 gui_internal_widget_table_first_row(GList * row)
@@ -905,8 +928,9 @@ gui_internal_widget_table_first_row(GList * row)
 }
 
 /**
- * @brief Get GList pointer to the table row drawn on the top of the screen.
- * @returns GList pointer to the top row in the children list, or NULL.
+ * @brief Gets GList pointer to the table row drawn on the top of the screen.
+ *
+ * @return GList pointer to the top row in the children list, or NULL.
  */
 GList *
 gui_internal_widget_table_top_row(struct gui_priv *this, struct widget * table)
@@ -919,8 +943,9 @@ gui_internal_widget_table_top_row(struct gui_priv *this, struct widget * table)
 }
 
 /**
- * @brief Set internal top row pointer of the table to point to a given row widget.
- * @returns GList pointer to the top row in the children list of the table.
+ * @brief Sets internal top row pointer of the table to point to a given row widget.
+ *
+ * @return GList pointer to the top row in the children list of the table.
  */
 GList *
 gui_internal_widget_table_set_top_row(struct gui_priv *this, struct widget * table, struct widget *row)
@@ -939,10 +964,12 @@ gui_internal_widget_table_set_top_row(struct gui_priv *this, struct widget * tab
 
 
 /**
- * Creates a new table_row widget.
+ * @brief Creates a new table_row widget.
+ *
  * @param this The graphics context
  * @param flags Sizing flags for the row
- * @returns The new table_row widget.
+ *
+ * @return The new table_row widget.
  */
 struct widget *
 gui_internal_widget_table_row_new(struct gui_priv * this, enum flags flags)
@@ -958,6 +985,7 @@ gui_internal_widget_table_row_new(struct gui_priv * this, enum flags flags)
 /**
  * @brief Computes the column dimensions for the table.
  *
+ * @param this The internal GUI instance
  * @param w The table widget to compute dimensions for.
  *
  * This function examines all of the rows and columns for the table w
@@ -983,7 +1011,7 @@ gui_internal_compute_table_dimensions(struct gui_priv * this,struct widget * w)
 	int total_width=0;
 	int column_count=0;
 
-	/**
+	/*
 	 * Scroll through the the table and
 	 * 1. Compute the maximum width + height of each column across all rows.
 	 */
@@ -1038,7 +1066,7 @@ gui_internal_compute_table_dimensions(struct gui_priv * this,struct widget * w)
 	} /*row loop */
 
 
-	/**
+	/*
 	 * If the width of all columns is less than the width off
 	 * the table expand each cell proportionally.
 	 *
@@ -1057,12 +1085,11 @@ gui_internal_compute_table_dimensions(struct gui_priv * this,struct widget * w)
 /**
  * @brief Computes the height and width for the table.
  *
- * The height and widht are computed to display all cells in the table
+ * The height and width are computed to display all cells in the table
  * at the requested height/width.
  *
  * @param this The graphics context
  * @param w The widget to pack.
- *
  */
 void
 gui_internal_table_pack(struct gui_priv * this, struct widget * w)
@@ -1109,7 +1136,7 @@ gui_internal_table_pack(struct gui_priv * this, struct widget * w)
 
 	if(w->h + w->c.y   > this->root.h   )
 	{
-		/**
+		/*
 		 * Do not allow the widget to exceed the screen.
 		 *
 		 */
@@ -1122,7 +1149,7 @@ gui_internal_table_pack(struct gui_priv * this, struct widget * w)
 	}
 
 
-	/**
+	/*
 	 * Deallocate column descriptions.
 	 */
 	g_list_foreach(column_data,(GFunc)g_free,NULL);
@@ -1133,7 +1160,7 @@ gui_internal_table_pack(struct gui_priv * this, struct widget * w)
 
 
 /**
- * @brief Invalidates coordinates for previosly rendered table widget rows.
+ * @brief Invalidates coordinates for previously rendered table widget rows.
  *
  * @param table_data Data from the table object.
  */
@@ -1182,7 +1209,7 @@ gui_internal_table_render(struct gui_priv * this, struct widget * w)
 		return;
 	y=w->p.y;
 	gui_internal_table_hide_rows(table_data);
-	/**
+	/*
 	 * Skip rows that are on previous pages.
 	 */
 	cur_row = w->children;
@@ -1193,7 +1220,7 @@ gui_internal_table_render(struct gui_priv * this, struct widget * w)
 	} else {
 		table_data->top_row=NULL;
 	}
-	/**
+	/*
 	 * Loop through each row.  Drawing each cell with the proper sizes,
 	 * at the proper positions.
 	 */
@@ -1298,7 +1325,7 @@ gui_internal_table_render(struct gui_priv * this, struct widget * w)
 		gui_internal_widget_render(this,table_data->scroll_buttons.button_box);
 	}
 
-	/**
+	/*
 	 * Deallocate column descriptions.
 	 */
 	g_list_foreach(column_desc,(GFunc)g_free,NULL);
@@ -1306,12 +1333,14 @@ gui_internal_table_render(struct gui_priv * this, struct widget * w)
 }
 
 /**
- * @brief handles the 'next page' table event.
+ * @brief Handles the 'next page' table event.
+ *
  * A callback function that is invoked when the 'next page' button is pressed
  * to advance the contents of a table widget.
  *
  * @param this The graphics context.
  * @param wm The button widget that was pressed.
+ * @param data
  */
 void
 gui_internal_table_button_next(struct gui_priv * this, struct widget * wm, void *data)
@@ -1345,7 +1374,8 @@ gui_internal_table_button_next(struct gui_priv * this, struct widget * wm, void
 
 
 /**
- * @brief handles the 'previous page' table event.
+ * @brief Handles the 'previous page' table event.
+ *
  * A callback function that is invoked when the 'previous page' button is pressed
  * to go back in the contents of a table widget.
  *
@@ -1386,18 +1416,14 @@ gui_internal_table_button_prev(struct gui_priv * this, struct widget * wm, void
 
 
 /**
- * @brief deallocates a table_data structure.
+ * @brief Deallocates a table_data structure.
  *
+ * @note button_box and its children (next_button,prev_button)
+ * have their memory managed by the table itself.
+ *
+ * @param p The table_data structure
  */
 void gui_internal_table_data_free(void * p)
 {
-
-
-	/**
-	 * @note button_box and its children (next_button,prev_button)
-	 * have their memory managed by the table itself.
-	 */
 	g_free(p);
-
-
 }
diff --git a/navit/osd.c b/navit/osd.c
index d5841b1ec..8bc0eb50c 100644
--- a/navit/osd.c
+++ b/navit/osd.c
@@ -237,11 +237,24 @@ osd_std_keypress(struct osd_item *item, struct navit *nav, char *key)
 		osd_evaluate_command(item, nav);
 }
 
+/**
+ * @brief Configures or unconfigures an OSD item.
+ *
+ * This method evaluates the result of the last execution of {@code cs}. If it evaluates to true, the
+ * item is configured, else it is unconfigured. (A configured item is displayed on the screen and can
+ * respond to user input, an unconfigured item is invisible and cannot receive user input.)
+ *
+ * If an error occurred during evaluation of {@code cs}, the item's configuration state is not changed.
+ *
+ * @param item The OSD item to reconfigure
+ * @param cs The command to evaluate
+ */
 static void
 osd_std_reconfigure(struct osd_item *item, struct command_saved *cs)
 {
 	char *err = NULL;	/* Error description */
 
+	dbg(lvl_debug, "enter, item=%p, cs=%p\n", item, cs);
 	if (!command_saved_error(cs)) {
 		item->configured = !! command_saved_get_int(cs);
 		if (item->gr && !(item->flags & 16)) 
@@ -336,7 +349,7 @@ osd_std_config(struct osd_item *item, struct navit *navit)
 	struct attr attr;
 	char *err = NULL;	/* Error description */
 
-	dbg(lvl_debug,"enter\n");
+	dbg(lvl_debug, "enter, item=%p, enable_cs=%p\n", item, item->enable_cs);
 	if (item->enable_cs) {
 		item->reconfig_cb = callback_new_1(callback_cast(osd_std_reconfigure), item);
 		command_saved_set_cb(item->enable_cs, item->reconfig_cb);
@@ -360,6 +373,7 @@ osd_std_config(struct osd_item *item, struct navit *navit)
 void
 osd_set_std_config(struct navit *nav, struct osd_item *item)
 {
+	dbg(lvl_debug, "enter, item=%p\n", item);
 	item->cb = callback_new_attr_2(callback_cast(osd_std_config), attr_osd_configuration, item, nav);
 	navit_add_callback(nav, item->cb);
 	osd_std_config(item, nav);