Merge from trunk.

Subversion-branch: /branches/opl-branch
Subversion-revision: 1624

1 files changed, 47 insertions, 3 deletions

diff --git a/textscreen/txt_window_action.h b/textscreen/txt_window_action.h
index 56f5a1b6..ab87f72c 100644
--- a/textscreen/txt_window_action.h
+++ b/textscreen/txt_window_action.h
@@ -22,6 +22,22 @@
 #ifndef TXT_WINDOW_ACTION_H
 #define TXT_WINDOW_ACTION_H
 
+/**
+ * @file txt_window_action.h
+ *
+ * Window action widget.
+ */
+
+/**
+ * Window action widget.
+ *
+ * A window action is attached to a window and corresponds to a
+ * keyboard shortcut that is active within that window.  When the
+ * key is pressed, the action is triggered.
+ *
+ * When a window action is triggered, the "pressed" signal is emitted.
+ */
+
 typedef struct txt_window_action_s txt_window_action_t;
 
 #include "txt_widget.h"
@@ -34,17 +50,45 @@ struct txt_window_action_s
     int key;
 };
 
+/**
+ * Create a new window action.
+ *
+ * @param key           The keyboard key that triggers this action.
+ * @param label         Label to display for this action in the tray
+ *                      at the bottom of the window.
+ * @return              Pointer to the new window action widget.
+ */
+
 txt_window_action_t *TXT_NewWindowAction(int key, char *label);
 
-// Creates an "escape" button that closes the window
+/**
+ * Create a new window action that closes the window when the
+ * escape key is pressed.  The label "Close" is used.
+ *
+ * @param window        The window to close.
+ * @return              Pointer to the new window action widget.
+ */
 
 txt_window_action_t *TXT_NewWindowEscapeAction(txt_window_t *window);
 
-// Same as above, but the button is named "abort"
+/**
+ * Create a new window action that closes the window when the
+ * escape key is pressed.  The label "Abort" is used.
+ *
+ * @param window        The window to close.
+ * @return              Pointer to the new window action widget.
+ */
 
 txt_window_action_t *TXT_NewWindowAbortAction(txt_window_t *window);
 
-// Accept button that does nothing
+/**
+ * Create a new "select" window action.  This does not really do
+ * anything, but reminds the user that "enter" can be pressed to
+ * activate the currently-selected widget.
+ *
+ * @param window        The window.
+ * @return              Pointer to the new window action widget.
+ */
 
 txt_window_action_t *TXT_NewWindowSelectAction(txt_window_t *window);