add details for doxygen

svn path=/trunk/; revision=11074

11 files changed, 255 insertions, 47 deletions

diff --git a/gtk/capture_prefs.h b/gtk/capture_prefs.h
index 1f5e06052c..9f526ef4ba 100644
--- a/gtk/capture_prefs.h
+++ b/gtk/capture_prefs.h
@@ -1,7 +1,7 @@
 /* capture_prefs.h
  * Definitions for capture preferences window
  *
- * $Id: capture_prefs.h,v 1.3 2004/06/01 20:28:04 ulfl Exp $
+ * $Id: capture_prefs.h,v 1.4 2004/06/02 18:44:10 ulfl Exp $
  *
  * Ethereal - Network traffic analyzer
  * By Gerald Combs <gerald@ethereal.com>
@@ -26,7 +26,7 @@
 #define __CAPTURE_PREFS_H__
 
 /** @file
- *  Capture preferences page.
+ *  "Capture" preferences page.
  */
 
 /** Build a capture preferences page.
diff --git a/gtk/column_prefs.h b/gtk/column_prefs.h
index 768de5e427..02113fd425 100644
--- a/gtk/column_prefs.h
+++ b/gtk/column_prefs.h
@@ -1,7 +1,7 @@
 /* column_prefs.h
  * Definitions for column preferences window
  *
- * $Id: column_prefs.h,v 1.5 2004/06/01 20:28:04 ulfl Exp $
+ * $Id: column_prefs.h,v 1.6 2004/06/02 18:44:10 ulfl Exp $
  *
  * Ethereal - Network traffic analyzer
  * By Gerald Combs <gerald@zing.org>
@@ -27,7 +27,7 @@
 #define __COLUMN_PREFS_H__
 
 /** @file
- *  Column preferences page.
+ *  "Column" preferences page.
  */
 
 /** Build a column preferences page.
diff --git a/gtk/gui_prefs.h b/gtk/gui_prefs.h
index 649c22b7e7..c6e268d63a 100644
--- a/gtk/gui_prefs.h
+++ b/gtk/gui_prefs.h
@@ -1,7 +1,7 @@
 /* gui_prefs.h
  * Definitions for GUI preferences window
  *
- * $Id: gui_prefs.h,v 1.6 2004/06/01 21:56:04 ulfl Exp $
+ * $Id: gui_prefs.h,v 1.7 2004/06/02 18:44:10 ulfl Exp $
  *
  * Ethereal - Network traffic analyzer
  * By Gerald Combs <gerald@zing.org>
@@ -27,7 +27,7 @@
 #define __GUI_PREFS_H__
 
 /** @file
- *  User interface and font preferences pages.
+ *  "User Interface" and "User Interface: Font" preferences pages.
  */
 
 /** Build a User interface preferences page.
diff --git a/gtk/layout_prefs.h b/gtk/layout_prefs.h
index b1193c03f5..c1baef40a8 100644
--- a/gtk/layout_prefs.h
+++ b/gtk/layout_prefs.h
@@ -1,7 +1,7 @@
 /* layout_prefs.h
  * Definitions for layout preferences window
  *
- * $Id: layout_prefs.h,v 1.3 2004/06/01 21:56:04 ulfl Exp $
+ * $Id: layout_prefs.h,v 1.4 2004/06/02 18:44:10 ulfl Exp $
  *
  * Ethereal - Network traffic analyzer
  * By Gerald Combs <gerald@ethereal.com>
@@ -26,7 +26,7 @@
 #define __LAYOUT_PREFS_H__
 
 /** @file
- *  User interface layout preferences pages.
+ *  "User Interface: Layout" preferences pages.
  */
 
 /** Build a User interface layout preferences page.
diff --git a/gtk/mtp3_stat.h b/gtk/mtp3_stat.h
index ebe55d31c8..26844fc536 100644
--- a/gtk/mtp3_stat.h
+++ b/gtk/mtp3_stat.h
@@ -1,6 +1,6 @@
 /* mtp3_stat.h
  *
- * $Id: mtp3_stat.h,v 1.1 2004/04/21 17:57:31 guy Exp $
+ * $Id: mtp3_stat.h,v 1.2 2004/06/02 18:44:10 ulfl Exp $
  *
  * Copyright 2004, Michael Lum <mlum [AT] telostech.com>,
  * In association with Telos Technology Inc.
@@ -24,6 +24,11 @@
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  */
 
+/** @file
+ *  Statistics for MTP3.
+ *  @todo Could someone with more knowledge of this comment it for doxygen?
+ */
+
 typedef struct _mtp3_stat_si_code_t {
     int				num_msus;
     double			size;
diff --git a/gtk/nameres_prefs.h b/gtk/nameres_prefs.h
index a988e9422f..676847d9e7 100644
--- a/gtk/nameres_prefs.h
+++ b/gtk/nameres_prefs.h
@@ -1,7 +1,7 @@
 /* nameres_prefs.h
  * Definitions for name resolution preferences window
  *
- * $Id: nameres_prefs.h,v 1.2 2002/08/28 21:03:48 jmayer Exp $
+ * $Id: nameres_prefs.h,v 1.3 2004/06/02 18:44:10 ulfl Exp $
  *
  * Ethereal - Network traffic analyzer
  * By Gerald Combs <gerald@ethereal.com>
@@ -25,9 +25,32 @@
 #ifndef __NAMERES_PREFS_H__
 #define __NAMERES_PREFS_H__
 
+/** @file
+ *  "Name resolution" preferences pages.
+ */
+
+/** Build a Name resolution preferences page.
+ *
+ * @return the new preferences page
+ */
 GtkWidget *nameres_prefs_show(void);
-void nameres_prefs_fetch(GtkWidget *w);
-void nameres_prefs_apply(GtkWidget *w);
-void nameres_prefs_destroy(GtkWidget *w);
+
+/** Fetch preference values from page.
+ *
+ * @param widget widget from nameres_prefs_show()
+ */
+void nameres_prefs_fetch(GtkWidget *widget);
+
+/** Apply preference values from page.
+ *
+ * @param widget widget from nameres_prefs_show()
+ */
+void nameres_prefs_apply(GtkWidget *widget);
+
+/** Destroy preference values from page.
+ *
+ * @param widget widget from nameres_prefs_show()
+ */
+void nameres_prefs_destroy(GtkWidget *widget);
 
 #endif
diff --git a/gtk/packet_list.h b/gtk/packet_list.h
index d38139a949..069a70d705 100644
--- a/gtk/packet_list.h
+++ b/gtk/packet_list.h
@@ -1,7 +1,7 @@
 /* packet_list.h
  * Declarations of GTK+-specific routines for managing the packet list.
  *
- * $Id: packet_list.h,v 1.2 2004/01/19 00:42:10 ulfl Exp $
+ * $Id: packet_list.h,v 1.3 2004/06/02 18:44:10 ulfl Exp $
  *
  * Ethereal - Network traffic analyzer
  * By Gerald Combs <gerald@ethereal.com>
@@ -25,23 +25,77 @@
 #ifndef __PACKET_LIST_H__
 #define __PACKET_LIST_H__
 
+/** @file
+ *  Main windows packet list.
+ */
+
+/** Create a new packet list.
+ *
+ * @param prefs current preferences
+ * @return the new packet list
+ */
 extern GtkWidget *packet_list_new(e_prefs *prefs);
+
+/** Fill in column titles.  This must be done after the top level window
+ *  is displayed.
+ *
+ * @todo is that still true, with fixed-width columns?
+ */
 extern void packet_list_set_column_titles(void);
 
-extern void mark_frame_cb(GtkWidget *, gpointer);
-extern void mark_all_frames_cb(GtkWidget *w, gpointer);
-extern void unmark_all_frames_cb(GtkWidget *w, gpointer);
+/** Mark the currently selected packet.
+ * 
+ * @param widget parent widget (unused)
+ * @param data unused
+ */
+extern void mark_frame_cb(GtkWidget *widget, gpointer data);
+
+/** Mark all packets in the list.
+ * 
+ * @param widget parent widget (unused)
+ * @param data unused
+ */
+extern void mark_all_frames_cb(GtkWidget *widget, gpointer data);
+
+/** Unmark all packets in the list.
+ * 
+ * @param widget parent widget (unused)
+ * @param data unused
+ */
+extern void unmark_all_frames_cb(GtkWidget *widget, gpointer data);
+
+/** Update packet marks. */
 extern void update_marked_frames(void);
 
-extern gboolean packet_list_get_event_row_column(GtkWidget *w,
+/** Gdk button click appeared, get row and column number in packet list from that position.
+ * 
+ * @param widget the packet list widget from packet_list_new()
+ * @param event_button the button event clicked
+ * @param row the row in the packet list
+ * @param column the column in the packet list
+ * @return TRUE if row/column is returned and in range
+ */
+extern gboolean packet_list_get_event_row_column(GtkWidget *widget,
     GdkEventButton *event_button, gint *row, gint *column);
 
 #if GTK_MAJOR_VERSION < 2
+/** Set the font of the packet list.
+ *
+ * @param font the new font
+ */
 extern void set_plist_font(GdkFont *font);
 #else
+/** Set the font of the packet list.
+ *
+ * @param font the new font
+ */
 extern void set_plist_font(PangoFontDescription *font);
 #endif
 
-extern void set_plist_sel_browse(gboolean);
+/** Set the selection mode of the packet list window.
+ *
+ * @param val TRUE for GTK_SELECTION_SINGLE, FALSE for GTK_SELECTION_BROWSE
+ */
+extern void set_plist_sel_browse(gboolean val);
 
 #endif /* __PACKET_LIST_H__ */
diff --git a/gtk/packet_win.h b/gtk/packet_win.h
index 86797e2765..7f5d711dd2 100644
--- a/gtk/packet_win.h
+++ b/gtk/packet_win.h
@@ -3,7 +3,7 @@
  *
  * Copyright 2000, Jeffrey C. Foster <jfoste@woodward.com>
  *
- * $Id: packet_win.h,v 1.9 2002/09/21 11:36:27 oabad Exp $
+ * $Id: packet_win.h,v 1.10 2004/06/02 18:44:10 ulfl Exp $
  *
  * Ethereal - Network traffic analyzer
  * By Gerald Combs <gerald@zing.org>
@@ -27,10 +27,17 @@
 #ifndef __PACKET_WIN_H__
 #define __PACKET_WIN_H__
 
-/* Create a new packet window. */
-extern void new_window_cb(GtkWidget *w);
+/** @file
+ *  Pop up a window to display the current packet only.
+ */
+
+/** Create a new packet window.
+ *
+ * @param widget parent widget (unused)
+ */
+extern void new_window_cb(GtkWidget *widget);
 
-/* Redraw the hex dump panes of all packet windows. */
+/** Redraw the hex dump panes of all packet windows. */
 void redraw_hex_dump_packet_wins(void);
 
 #endif
diff --git a/gtk/prefs_dlg.h b/gtk/prefs_dlg.h
index 5b5b9d288e..0f5ee294cb 100644
--- a/gtk/prefs_dlg.h
+++ b/gtk/prefs_dlg.h
@@ -1,7 +1,7 @@
 /* prefs_dlg.h
  * Definitions for preference handling routines
  *
- * $Id: prefs_dlg.h,v 1.10 2004/05/27 16:50:16 ulfl Exp $
+ * $Id: prefs_dlg.h,v 1.11 2004/06/02 18:44:10 ulfl Exp $
  *
  * Ethereal - Network traffic analyzer
  * By Gerald Combs <gerald@ethereal.com>
@@ -25,20 +25,92 @@
 #ifndef __PREFS_DLG_H__
 #define __PREFS_DLG_H__
 
-void       prefs_cb(GtkWidget *, gpointer);
-void       properties_cb(GtkWidget *, gpointer);
-
-#define E_TOOLTIPS_KEY          "tooltips"
-
-GtkWidget *create_preference_check_button(GtkWidget *, int, const gchar *,
-    const gchar *, gboolean);
-GtkWidget *create_preference_radio_buttons(GtkWidget *, int, const gchar *,
-    const gchar *, const enum_val_t *, gint);
-gint fetch_preference_radio_buttons_val(GtkWidget *, const enum_val_t *);
-GtkWidget *create_preference_option_menu(GtkWidget *, int, const gchar *,
-    const gchar *, const enum_val_t *, gint);
-gint fetch_preference_option_menu_val(GtkWidget *, const enum_val_t *);
-GtkWidget *create_preference_entry(GtkWidget *, int, const gchar *,
-    const gchar *, char *);
+/** @file
+ * "Preferences" and "Protocol properties" dialog boxes.
+ */
+
+/** Show the preferences dialog.
+ * 
+ * @param widget parent widget (unused)
+ * @param data unused
+ */
+extern void prefs_cb(GtkWidget *widget, gpointer data);
+
+/** Show the protocol properties dialog.
+ * 
+ * @param widget parent widget (unused)
+ * @param data unused
+ */
+extern void properties_cb(GtkWidget *widget, gpointer data);
+
+#define E_TOOLTIPS_KEY "tooltips"
+
+/** Create a check button for a preferences page.
+ *
+ * @param main_tb the table to put this button into
+ * @param table_row row in the table
+ * @param label_text the label text for the left side
+ * @param tooltip_text the tooltip for this check button
+ * @param active the check button is initially active
+ * @return the new check button
+ */
+extern GtkWidget *create_preference_check_button(GtkWidget *main_tb, int table_row,
+    const gchar *label_text, const gchar *tooltip_text, gboolean active);
+
+/** Create a radio button for a preferences page.
+ *
+ * @param main_tb the table to put this button into
+ * @param table_row row in the table
+ * @param label_text the label text for the left side
+ * @param tooltip_text the tooltip for this radio button
+ * @param enumvals the values
+ * @param current_val the initially selected value
+ * @return the new radio button
+ */
+extern GtkWidget *create_preference_radio_buttons(GtkWidget *main_tb, int table_row,
+    const gchar *label_text, const gchar *tooltip_text,
+    const enum_val_t *enumvals, gint current_val);
+
+/** Get the currently selected value from a radio button.
+ * 
+ * @param button the button from create_preference_radio_buttons()
+ * @param enumvals the same enum vals as in create_preference_radio_buttons()
+ * @return the index of the currently selected item
+ */
+extern gint fetch_preference_radio_buttons_val(GtkWidget *button, const enum_val_t *enumvals);
+
+/** Create an option menu for a preferences page.
+ *
+ * @param main_tb the table to put this menu into
+ * @param table_row row in the table
+ * @param label_text the label text for the left side
+ * @param tooltip_text the tooltip for this option menu
+ * @param enumvals the values
+ * @param current_val the initially selected value
+ * @return the new option menu
+ */
+extern GtkWidget *create_preference_option_menu(GtkWidget *main_tb, int table_row,
+    const gchar *label_text, const gchar *tooltip_text,
+    const enum_val_t *enumvals, gint current_val);
+
+/** Get the currently selected value from an option menu.
+ * 
+ * @param optmenu the option menu from create_preference_option_menu()
+ * @param enumvals the same enum vals as in create_preference_option_menu()
+ * @return the index of the currently selected item
+ */
+extern gint fetch_preference_option_menu_val(GtkWidget *optmenu, const enum_val_t *enumvals);
+
+/** Create a text entry for a preferences page.
+ *
+ * @param main_tb the table to put this entry into
+ * @param table_row row in the table
+ * @param label_text the label text for the left side
+ * @param tooltip_text the tooltip for this text entry
+ * @param value the initially value
+ * @return the new text entry
+ */
+extern GtkWidget *create_preference_entry(GtkWidget *main_tb, int table_row,
+    const gchar *label_text, const gchar *tooltip_text, char *value);
 
 #endif
diff --git a/gtk/print_prefs.h b/gtk/print_prefs.h
index 1b9b3b3734..4280afadee 100644
--- a/gtk/print_prefs.h
+++ b/gtk/print_prefs.h
@@ -1,7 +1,7 @@
 /* print_prefs.h
  * Definitions for print preferences window
  *
- * $Id: print_prefs.h,v 1.6 2002/08/28 21:03:49 jmayer Exp $
+ * $Id: print_prefs.h,v 1.7 2004/06/02 18:44:10 ulfl Exp $
  *
  * Ethereal - Network traffic analyzer
  * By Gerald Combs <gerald@zing.org>
@@ -26,9 +26,32 @@
 #ifndef __PRINT_PREFS_H__
 #define __PRINT_PREFS_H__
 
+/** @file
+ *  "Print" preferences pages.
+ */
+
+/** Build a Print preferences page.
+ *
+ * @return the new preferences page
+ */
 GtkWidget *printer_prefs_show(void);
-void printer_prefs_fetch(GtkWidget *w);
-void printer_prefs_apply(GtkWidget *w);
-void printer_prefs_destroy(GtkWidget *w);
+
+/** Fetch preference values from page.
+ *
+ * @param widget widget from printer_prefs_show()
+ */
+void printer_prefs_fetch(GtkWidget *widget);
+
+/** Apply preference values from page.
+ *
+ * @param widget widget from printer_prefs_show()
+ */
+void printer_prefs_apply(GtkWidget *widget);
+
+/** Destroy preference values from page.
+ *
+ * @param widget widget from printer_prefs_show()
+ */
+void printer_prefs_destroy(GtkWidget *widget);
 
 #endif
diff --git a/gtk/stream_prefs.h b/gtk/stream_prefs.h
index 00d87bb8f7..8712ad0a90 100644
--- a/gtk/stream_prefs.h
+++ b/gtk/stream_prefs.h
@@ -1,7 +1,7 @@
 /* stream_prefs.h
  * Definitions for stream preferences window
  *
- * $Id: stream_prefs.h,v 1.4 2002/08/28 21:03:49 jmayer Exp $
+ * $Id: stream_prefs.h,v 1.5 2004/06/02 18:44:10 ulfl Exp $
  *
  * Ethereal - Network traffic analyzer
  * By Gerald Combs <gerald@zing.org>
@@ -26,9 +26,33 @@
 #ifndef __STREAM_PREFS_H__
 #define __STREAM_PREFS_H__
 
+/** @file
+ *  "User Interface: Colors" preferences pages.
+ *  @todo rename functions and files from stream to colors
+ */
+
+/** Build a Colors preferences page.
+ *
+ * @return the new preferences page
+ */
 GtkWidget *stream_prefs_show(void);
-void stream_prefs_fetch(GtkWidget *w);
-void stream_prefs_apply(GtkWidget *w);
-void stream_prefs_destroy(GtkWidget *w);
+
+/** Fetch preference values from page.
+ *
+ * @param widget widget from stream_prefs_show()
+ */
+void stream_prefs_fetch(GtkWidget *widget);
+
+/** Apply preference values from page.
+ *
+ * @param widget widget from stream_prefs_show()
+ */
+void stream_prefs_apply(GtkWidget *widget);
+
+/** Destroy preference values from page.
+ *
+ * @param widget widget from stream_prefs_show()
+ */
+void stream_prefs_destroy(GtkWidget *widget);
 
 #endif