add more details for doxygen

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

4 files changed, 70 insertions, 41 deletions

diff --git a/gtk/dlg_utils.h b/gtk/dlg_utils.h
index 76f0bf8566..3be89cb3a4 100644
--- 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.20 2004/06/04 17:16:57 ulfl Exp $
+ * $Id: dlg_utils.h,v 1.21 2004/06/05 12:12:13 ulfl Exp $
  *
  * Ethereal - Network traffic analyzer
  * By Gerald Combs <gerald@ethereal.com>
@@ -116,8 +116,7 @@ extern GtkWidget *file_selection_new(const gchar *title, file_selection_action_t
  *
  * @param fs the file selection dialog from file_selection_new()
  * @param filename the folder to set
- * @return ???
- * @todo what's the return value?
+ * @return TRUE if the folder could be changed successfully
  */
 extern gboolean file_selection_set_current_folder(GtkWidget *fs, const gchar *filename);
 
@@ -129,7 +128,8 @@ extern gboolean file_selection_set_current_folder(GtkWidget *fs, const gchar *fi
  */
 extern void file_selection_set_extra_widget(GtkWidget *fs, GtkWidget *extra);
 
-/** @todo ??? */
+/** The function file_selection_browse() will OBJECT_SET_DATA() itself on it's parent window.
+ *  When destroying the parent window, it can close the corresponding file selection. */
 #define E_FILE_SEL_DIALOG_PTR_KEY "file_sel_dialog_ptr"
 
 /** Browse the files and fill in the associated text entry.
@@ -138,7 +138,6 @@ extern void file_selection_set_extra_widget(GtkWidget *fs, GtkWidget *extra);
  * @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 parent widget as the first parameter, not the button
  */
 extern void
 file_selection_browse(GtkWidget *file_bt, GtkWidget *file_te, const char *title, file_selection_action_t action);
diff --git a/gtk/filter_prefs.h b/gtk/filter_prefs.h
index 42b78eeedc..2d2e9aa5c6 100644
--- a/gtk/filter_prefs.h
+++ b/gtk/filter_prefs.h
@@ -3,7 +3,7 @@
  * (This used to be a notebook page under "Preferences", hence the
  * "prefs" in the file name.)
  *
- * $Id: filter_prefs.h,v 1.20 2004/06/04 20:05:31 ulfl Exp $
+ * $Id: filter_prefs.h,v 1.21 2004/06/05 12:12:13 ulfl Exp $
  *
  * Ethereal - Network traffic analyzer
  * By Gerald Combs <gerald@ethereal.com>
@@ -111,16 +111,15 @@ void colorize_filter_te_as_valid(GtkWidget *widget);
  */
 void filter_te_syntax_check_cb(GtkWidget *widget);
 
-/** ???
- * @todo check usage of this define */
+/** The filter button of the top_level window. */
 #define E_FILT_BT_PTR_KEY	    "filter_bt_ptr"
 
-/** ???
- * @todo check usage of this define */
+/** The filter text entry. */
 #define E_FILT_TE_PTR_KEY	    "filter_te_ptr"
 
-/** ???
- * @todo check usage of this define */
+/** The filter text entry.
+ *  @todo Check the usage of all the text entry keys.
+ */
 #define E_FILT_FILTER_TE_KEY    "filter_filter_te"
 
 #endif /* filter.h */
diff --git a/gtk/gtkglobals.h b/gtk/gtkglobals.h
index afa914f93c..d2e428afe0 100644
--- a/gtk/gtkglobals.h
+++ b/gtk/gtkglobals.h
@@ -1,7 +1,7 @@
 /* gtkglobals.h
  * GTK-related Global defines, etc.
  *
- * $Id: gtkglobals.h,v 1.28 2004/06/04 20:05:31 ulfl Exp $
+ * $Id: gtkglobals.h,v 1.29 2004/06/05 12:12:13 ulfl Exp $
  *
  * Ethereal - Network traffic analyzer
  * By Gerald Combs <gerald@ethereal.com>
@@ -39,38 +39,36 @@
  *  GTK global definitions. For example a pointer to the main application window.
  */
 
-/** application window */
+/** Application window. */
 extern GtkWidget *top_level;
 
-/** packet list pane */
+/** Packet list pane. */
 extern GtkWidget *packet_list;
 
-/** tree view (packet details) pane */
+/** Tree view (packet details) pane. */
 extern GtkWidget *tree_view;
 
-/** byte notebook (packet bytes) pane */
+/** Byte notebook (packet bytes) pane. */
 extern GtkWidget *byte_nb_ptr;
 
-/** the filter text entry in the filter toolbar */
+/** The filter text entry in the filter toolbar. */
 extern GtkWidget   *main_display_filter_widget;
 
 #if GTK_MAJOR_VERSION < 2
-/** normal font */
+/** Normal font. */
 extern GdkFont   *m_r_font;
-/** bold font */
+/** Bold font. */
 extern GdkFont   *m_b_font;
-/** font height */
+/** Font height. */
 extern guint      m_font_height;
-/** font width */
+/** Font width. */
 extern guint      m_font_width;
-/** ??? 
- * @todo what's this?
- */
+/** Widget style (font, color, ...). */
 extern GtkStyle  *item_style;
 #else
-/** normal font */
+/** Normal font. */
 extern PangoFontDescription *m_r_font;
-/** bold font */
+/** Bold font. */
 extern PangoFontDescription *m_b_font;
 #endif
 
diff --git a/gtk/service_response_time_table.h b/gtk/service_response_time_table.h
index 74e3b47942..f99bb3d527 100644
--- a/gtk/service_response_time_table.h
+++ b/gtk/service_response_time_table.h
@@ -3,7 +3,7 @@
  * Helper routines common to all service response time statistics
  * tap.
  *
- * $Id: service_response_time_table.h,v 1.3 2004/06/02 22:13:04 ulfl Exp $
+ * $Id: service_response_time_table.h,v 1.4 2004/06/05 12:12:13 ulfl Exp $
  *
  * Ethereal - Network traffic analyzer
  * By Gerald Combs <gerald@ethereal.com>
@@ -28,37 +28,70 @@
 #include "epan/nstime.h"
 
 /** @file
- * Helper routines common to all service response time statistics tap.
- *  @todo complete this?
+ *  Helper routines common to all service response time statistics tap.
  */
 
+/** Procedure data */
 typedef struct _srt_procedure_t {
-	char *entries[6];
-	int num;
-	nstime_t min;
-	nstime_t max;
-	nstime_t tot;
+	char *entries[6];   /**< column entries */
+	int num;            /**< number of calls seen */
+	nstime_t min;       /**< minimum srt */
+	nstime_t max;       /**< maximum srt */
+	nstime_t tot;       /**< average srt */
 } srt_procedure_t;
 
+/** Statistics table */
 typedef struct _srt_stat_table {
-	GtkWidget *scrolled_window;
-	GtkCList *table;
-	GtkWidget *menu;
-	char *filter_string; /* append procedure number (%d) to this string 
+	GtkWidget *scrolled_window; /**< window widget */
+	GtkCList *table;            /**< table widget */
+	GtkWidget *menu;            /**< context menu */
+	char *filter_string;        /**< append procedure number (%d) to this string 
 				to create a display filter */
-	int num_procs;
-	srt_procedure_t *procedures;
+	int num_procs;              /**< number of elements on procedures array */
+	srt_procedure_t *procedures;/**< the procedures array */
 } srt_stat_table;
 
+/** Init an srt table data structure.
+ *
+ * @param rst the srt table to init
+ * @param num_procs number of procedures
+ * @param vbox the corresponding GtkVBox to fill in
+ * @param filter_string filter string or NULL
+ */
 void init_srt_table(srt_stat_table *rst, int num_procs, GtkWidget *vbox, char *filter_string);
 
+/** Init an srt table row data structure.
+ *
+ * @param rst the srt table
+ * @param index number of procedure
+ * @param procedure the procedures name
+ */
 void init_srt_table_row(srt_stat_table *rst, int index, char *procedure);
 
+/** Add srt response to table row data. This will not draw the data!
+ *
+ * @param rst the srt table
+ * @param index number of procedure
+ * @param req_time the time of the corresponding request
+ * @param pinfo current packet info
+ */
 void add_srt_table_data(srt_stat_table *rst, int index, nstime_t *req_time, packet_info *pinfo);
 
+/** Draw the srt table data.
+ *
+ * @param rst the srt table
+ */
 void draw_srt_table_data(srt_stat_table *rst);
 
+/** Reset the srt table data.
+ *
+ * @param rst the srt table
+ */
 void reset_srt_table_data(srt_stat_table *rst);
 
+/** Free the srt table data.
+ *
+ * @param rst the srt table
+ */
 void free_srt_table_data(srt_stat_table *rst);