Refactor:core:Add some docs and debug output to OSD and command code

Signed-off-by: mvglasow <michael -at- vonglasow.com>

2 files changed, 50 insertions, 2 deletions

diff --git a/navit/command.c b/navit/command.c
index 812abbc90..e1d49293b 100644
--- a/navit/command.c
+++ b/navit/command.c
@@ -1495,9 +1495,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 +1528,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;
@@ -1573,6 +1596,14 @@ 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.
+ *
+ * @param cs The command
+ */
 static int
 command_register_callbacks(struct command_saved *cs)
 {
@@ -1581,6 +1612,7 @@ command_register_callbacks(struct command_saved *cs)
 	struct object_func *func;
 	struct callback *cb;
 	
+	dbg(lvl_error, "enter: cs=%p, cs->async=%d, cs->command=%s\n", cs, cs->async, cs->command);
 	attr = cs->context_attr;
 	cs->ctx.expr = cs->command;
 	cs->ctx.attr = &attr;
@@ -1591,6 +1623,7 @@ command_register_callbacks(struct command_saved *cs)
 
 		if (cs->ctx.error || (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 an object: cs=%p, cs->ctx.error=%d, cs->ctx.expr=%s\n", cs, cs->ctx.error, cs->ctx.expr);
 			return 0;
 		}
 
@@ -1619,7 +1652,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,6 +1665,7 @@ 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;
 }
 
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);