Add documentation for high-level textscreen functions.

Subversion-branch: /trunk/chocolate-doom
Subversion-revision: 1449

1 files changed, 37 insertions, 0 deletions

diff --git a/textscreen/txt_radiobutton.h b/textscreen/txt_radiobutton.h
index d668254c..b1d6487c 100644
--- a/textscreen/txt_radiobutton.h
+++ b/textscreen/txt_radiobutton.h
@@ -22,6 +22,24 @@
 #ifndef TXT_RADIOBUTTON_H
 #define TXT_RADIOBUTTON_H
 
+/**
+ * A radio button widget.
+ *
+ * Radio buttons are typically used in groups, to allow a value to be
+ * selected from a range of options.  Each radio button corresponds
+ * to a particular option that may be selected.  A radio button
+ * has an indicator to indicate whether it is the currently-selected
+ * value, and a text label.
+ *
+ * Internally, a radio button tracks an integer variable that may take
+ * a range of different values.  Each radio button has a particular
+ * value associated with it; if the variable is equal to that value,
+ * the radio button appears selected.  If a radio button is pressed
+ * by the user through the GUI, the variable is set to its value.
+ *
+ * When a radio button is selected, the "selected" signal is emitted.
+ */
+
 typedef struct txt_radiobutton_s txt_radiobutton_t;
 
 #include "txt_widget.h"
@@ -34,7 +52,26 @@ struct txt_radiobutton_s
     int value;
 };
 
+/**
+ * Create a new radio button widget.
+ *
+ * @param label          The label to display next to the radio button.
+ * @param variable       Pointer to the variable tracking whether this
+ *                       radio button is selected.
+ * @param value          If the variable is equal to this value, the
+ *                       radio button appears selected.
+ * @return               Pointer to the new radio button widget.
+ */
+
 txt_radiobutton_t *TXT_NewRadioButton(char *label, int *variable, int value);
+
+/**
+ * Set the label on a radio button.
+ *
+ * @param radiobutton    The radio button.
+ * @param value          The new label.
+ */
+
 void TXT_SetRadioButtonLabel(txt_radiobutton_t *radiobutton, char *value);
 
 #endif /* #ifndef TXT_RADIOBUTTON_H */