From: Andre Noll <maan@tuebingen.mpg.de>
Date: Sat, 6 Sep 2014 00:34:59 +0000 (+0200)
Subject: gui: Add documentation of public functions.
X-Git-Url: http://git.tue.mpg.de/?a=commitdiff_plain;h=82c0b7aa776ecb2250ebd8ae6f797298d62497fd;p=gsu.git

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 3c89567..2d3e270 100644
--- 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