add details for doxygen

git-svn-id: http://anonsvn.wireshark.org/wireshark/trunk@11045 f5534014-38df-0310-8fa8-9805f1628bb7

diff --git a/gtk/dlg_utils.h b/gtk/dlg_utils.h
index 75380ee677b202bd7b2c77074c8c59bfcf2e050a..a2e99f713d7308aaac442d27a2cb4e513c57ca29 100644 (file)
--- a/gtk/dlg_utils.h
+++ b/gtk/dlg_utils.h
@@ -1,7 +1,7 @@
 /* dlg_utils.h
  * Declarations of utilities to use when constructing dialogs
  *
- * $Id: dlg_utils.h,v 1.15 2004/05/26 03:49:22 ulfl Exp $
+ * $Id: dlg_utils.h,v 1.16 2004/05/31 13:42:58 ulfl Exp $
  *
  * Ethereal - Network traffic analyzer
  * By Gerald Combs <gerald@ethereal.com>
@@ -22,47 +22,96 @@
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  */
 
+/** @file
+ * This file will provide utility functions for dialog windows related to Ethereal's main window.
+ * It's depending on the window functions in ui_util.h. See window_new() and others in
+ * ui_util.h for further explanation of dialogs and windows in Ethereal.
+ */
+
 #ifndef __DLG_UTILS_H__
 #define __DLG_UTILS_H__
 
-/* Create a dialog box window that belongs to Ethereal's main window,
- * see wíndow_new() for usage */
+/** Create a dialog box window that belongs to Ethereal's main window.
+ *  See window_new() for usage.
+ *
+ * @param title the title for the new dialog
+ * @return the newly created dialog
+ */
 extern GtkWidget *dlg_window_new(const gchar *title);
 
-/* Create a file selection dialog box window that belongs to Ethereal's
-   main window. */
+/** the action a file selection is designed for */
 typedef enum {
-       FILE_SELECTION_OPEN,
-       FILE_SELECTION_SAVE
+       FILE_SELECTION_OPEN,    /**< open a file */
+       FILE_SELECTION_SAVE     /**< save/export a file */
 } file_selection_action_t;
+
+/** Create a file selection dialog box window that belongs to Ethereal's
+ *  main window. See window_new() for usage.
+ *
+ * @param title the title for the new file selection dialog
+ * @param action the desired action
+ * @return the newly created file selection dialog
+ */
 extern GtkWidget *file_selection_new(const gchar *title, file_selection_action_t action);
 
-/* Set the current folder for a file selection dialog. */
+/** Set the current folder for a file selection dialog.
+ *
+ * @param fs the file selection dialog from file_selection_new()
+ * @param filename the folder to set
+ * @return ???
+ * @todo what's the return value?
+ */
 extern gboolean file_selection_set_current_folder(GtkWidget *fs, const gchar *filename);
 
-/* Set the "extra" widget for a file selection dialog, with user-supplied
-   options. */
+/** Set the "extra" widget for a file selection dialog. This is needed to support 
+ *  user-supplied options.
+ *
+ * @param fs the file selection dialog from file_selection_new()
+ * @param extra the widget to set
+ */
 extern void file_selection_set_extra_widget(GtkWidget *fs, GtkWidget *extra);
 
+/** @todo ??? */
 #define E_FILE_SEL_DIALOG_PTR_KEY "file_sel_dialog_ptr"
 
+/** Browse the files and fill in the associated text entry.
+ *
+ * @param file_bt the button that called us (to get the toplevel widget)
+ * @param file_te the GtkEntry the dialog will have to fill in the filename
+ * @param title the title for the file selection dialog
+ * @param action the desired action
+ * @todo use the toplevel widget as the parameter, not the button
+ */
 extern void
-file_selection_browse(GtkWidget *file_bt, GtkWidget *file_te, const char *label, file_selection_action_t action);
+file_selection_browse(GtkWidget *file_bt, GtkWidget *file_te, const char *title, file_selection_action_t action);
 
-/* Create a button row for a dialog */
-/* the button widgets will be available by OBJECT_GET_DATA(stock_id) */
+/** Create a button row (with variable number of buttons) for a dialog.
+ *  The button widgets will be available by OBJECT_GET_DATA(dlg, stock_id) later.
+ *
+ * @param stock_id_first the first button (e.g. GTK_STOCK_OK)
+ * @param ... the next buttons, just like stock_id_first
+ * @return the new button row
+ * @todo move this to ui_util.h
+ */
 extern GtkWidget *dlg_button_row_new(gchar *stock_id_first, ...);
 
-/* Set the "activate" signal for a widget to call a routine to
-   activate the "OK" button for a dialog box. */
+/** Set the "activate" signal for a widget to call a routine to
+ *  activate the "OK" button for a dialog box.
+ *
+ * @param widget a widget which should be connected (usually a GtkEntry)
+ * @param ok_button the button to be activated
+ * @todo move this to ui_util.h
+ */
 extern void dlg_set_activate(GtkWidget *widget, GtkWidget *ok_button);
 
 
-/* used by compat_macros.h only */
+/** used by compat_macros.h only, don't use directly */
 extern GtkWidget *dlg_radio_button_new_with_label_with_mnemonic(GSList *group,
     const gchar *label, GtkAccelGroup *accel_group);
+/** used by compat_macros.h only, don't use directly */
 extern GtkWidget *dlg_check_button_new_with_label_with_mnemonic(const gchar *label,
     GtkAccelGroup *accel_group);
+/** used by compat_macros.h only, don't use directly */
 extern GtkWidget *dlg_toggle_button_new_with_label_with_mnemonic(const gchar *label,
                        GtkAccelGroup *accel_group);