gui: Add documentation of public functions.

The functions gsu_inputbox(), gsu_textbox() and gsu_msgbox() were not
documented at all. This commit adds summary, usage and a description
for each.

diff --git a/gui b/gui
index 3c89567cceae816d58cd9bd438ce0fe2d8cf2410..2d3e270371a8db341052455eda1fdc7891dcb563 100644 (file)
--- a/gui
+++ b/gui
@@ -22,6 +22,14 @@ _get_geometry()
        result="$y $x"
 }
 
+# Open a dialog box which asks the user to input a text
+#
+# Usage: gsu_input_box <text> <init>
+#
+# <text> is displayed above of the input field, which is is preset to <init>.
+# The entered text is returned in $result. On success (user pressed OK)
+# the function returns zero. If the user selected Cancel, the return value is
+# one. On dialog errors, a negative error code is returned.
 gsu_inputbox()
 {
        local g text="$1" init="$2"
@@ -37,6 +45,11 @@ gsu_inputbox()
        ret=$GSU_SUCCESS
 }
 
+# Show the given file in a text box
+#
+# Usage: gsu_textbox <path>
+#
+# The box has an OK button which closes the box when activated.
 gsu_textbox()
 {
        local g file="$1"
@@ -50,9 +63,15 @@ gsu_textbox()
        ret=$GSU_SUCCESS
 }
 
-# dialog segfaults if message is too long. Hence we always use a temporary file
+# Show a message in a text box
+#
+# Usage: gsu_msgbox <text>
+#
+# This is like gsu_textbox() but the text is passed as a string.
 gsu_msgbox()
 {
+       # Some versions of dialog segfault if the text is too long. Hence we
+       # always use a temporary file.
        local tmp="$(mktemp gsu_msgbox.XXXXXXXXXX)"
 
        if (($? != 0)); then