add more details for doxygen
authorulfl <ulfl@f5534014-38df-0310-8fa8-9805f1628bb7>
Fri, 4 Jun 2004 17:19:01 +0000 (17:19 +0000)
committerulfl <ulfl@f5534014-38df-0310-8fa8-9805f1628bb7>
Fri, 4 Jun 2004 17:19:01 +0000 (17:19 +0000)
git-svn-id: http://anonsvn.wireshark.org/wireshark/trunk@11107 f5534014-38df-0310-8fa8-9805f1628bb7

12 files changed:
capture.h
gtk/Makefile.nmake
gtk/dlg_utils.h
gtk/doxygen.cfg
gtk/gtkglobals.h
gtk/main.h
gtk/menu.h
gtk/packet_list.h
gtk/proto_draw.h
gtk/recent.h
gtk/toolbar.h
gtk/ui_util.h

index a7fafe16576dc4791d3b45a794c7e35a4419dd9f..0191638bc78717bbe669bf31d89c3a9601397847 100644 (file)
--- a/capture.h
+++ b/capture.h
@@ -1,7 +1,7 @@
 /* capture.h
  * Definitions for packet capture windows
  *
- * $Id: capture.h,v 1.45 2004/04/13 18:01:39 tuexen Exp $
+ * $Id: capture.h,v 1.46 2004/06/04 17:19:01 ulfl Exp $
  *
  * Ethereal - Network traffic analyzer
  * By Gerald Combs <gerald@ethereal.com>
 
 #ifdef HAVE_LIBPCAP
 
-/* Name we give to the child process when doing a "-S" capture. */
+/** @file
+ *  Capture related things.
+ */
+
+/** Name we give to the child process when doing a "-S" capture. */
 #define        CHILD_NAME      "ethereal-capture"
 
+/** Capture options coming from user interface */
 typedef struct {
 #ifdef _WIN32
-    int buffer_size;        /* the capture buffer size (MB) */
+    int buffer_size;        /**< the capture buffer size (MB) */
 #endif
-       gboolean has_snaplen;           /* TRUE if maximum capture packet
+       gboolean has_snaplen;           /**< TRUE if maximum capture packet
                                           length is specified */
-       int snaplen;                    /* Maximum captured packet length */
-       int promisc_mode;               /* Capture in promiscuous mode */
-       int linktype;                   /* Data link type to use, or -1 for
+       int snaplen;                    /**< Maximum captured packet length */
+       int promisc_mode;               /**< Capture in promiscuous mode */
+       int linktype;                   /**< Data link type to use, or -1 for
                                           "use default" */
-       int sync_mode;                  /* Fork a child to do the capture,
+       int sync_mode;                  /**< Fork a child to do the capture,
                                           and sync between them */
 
-    gboolean multi_files_on;    /* TRUE if ring buffer in use */
+    gboolean multi_files_on;    /**< TRUE if ring buffer in use */
 
-       gboolean has_file_duration;     /* TRUE if ring duration specified */
+       gboolean has_file_duration;     /**< TRUE if ring duration specified */
        gint32 file_duration;     /* Switch file after n seconds */
-       gboolean has_ring_num_files;/* TRUE if ring num_files specified */
-       guint32 ring_num_files;         /* Number of multiple buffer files */
-    gboolean has_autostop_files;/* TRUE if maximum number of capture files
+       gboolean has_ring_num_files;/**< TRUE if ring num_files specified */
+       guint32 ring_num_files;         /**< Number of multiple buffer files */
+    gboolean has_autostop_files;/**< TRUE if maximum number of capture files
                                           are specified */
-    gint32 autostop_files;      /* Maximum number of capture files */
+    gint32 autostop_files;      /**< Maximum number of capture files */
 
-    gboolean has_autostop_packets;     /* TRUE if maximum packet count is
+    gboolean has_autostop_packets;     /**< TRUE if maximum packet count is
                                           specified */
-       int autostop_packets;           /* Maximum packet count */
-       gboolean has_autostop_filesize; /* TRUE if maximum capture file size
+       int autostop_packets;           /**< Maximum packet count */
+       gboolean has_autostop_filesize; /**< TRUE if maximum capture file size
                                           is specified */
-       gint32 autostop_filesize;       /* Maximum capture file size */
-       gboolean has_autostop_duration; /* TRUE if maximum capture duration
+       gint32 autostop_filesize;       /**< Maximum capture file size */
+       gboolean has_autostop_duration; /**< TRUE if maximum capture duration
                                           is specified */
-       gint32 autostop_duration;       /* Maximum capture duration */
+       gint32 autostop_duration;       /**< Maximum capture duration */
 } capture_options;
 
+/** Global capture options. */
 extern capture_options capture_opts;
 
-extern gboolean quit_after_cap; /* Makes a "capture only mode". Implies -k */
-extern gboolean capture_child; /* if this is the child for "-S" */
+/** Makes a "capture only mode". Implies -k */
+extern gboolean quit_after_cap; 
 
-/* Open a specified file, or create a temporary file, and start a capture
+/** If this is the child for "-S" */
+extern gboolean capture_child; 
+
+/** Open a specified file, or create a temporary file, and start a capture
    to the file in question.  Returns TRUE if the capture starts
    successfully, FALSE otherwise. */
 gboolean do_capture(const char *save_file);
 
-/* Do the low-level work of a capture. */
+/** Do the low-level work of a capture. */
 int    capture(gboolean *stats_known, struct pcap_stat *stats);
 
-/* Stop a capture from a menu item. */
+/** Stop a capture from a menu item. */
 void   capture_stop(void);
 
-/* Terminate the capture child cleanly when exiting. */
+/** Terminate the capture child cleanly when exiting. */
 void   kill_capture_child(void);
 
-
-/* XXX: improve this macro (put something like this into epan/packet.h?) */
+/** Number of packet counts.
+ * @todo improve this macro (put something like this into epan/packet.h?) */
 #define CAPTURE_PACKET_COUNTS sizeof(packet_counts) / sizeof (gint)
 
+/** Current Capture info. */
 typedef struct {
     /* handles */
-    gpointer        callback_data;  /* capture callback handle */
-    gpointer        ui;             /* user interfaces own handle */
+    gpointer        callback_data;  /**< capture callback handle */
+    gpointer        ui;             /**< user interfaces own handle */
 
     /* capture info */
-    packet_counts   *counts;        /* protocol specific counters */
-    time_t          running_time;   /* running time since last update */
-    gint            new_packets;    /* packets since last update */
+    packet_counts   *counts;        /**< protocol specific counters */
+    time_t          running_time;   /**< running time since last update */
+    gint            new_packets;    /**< packets since last update */
 } capture_info;
 
 
-/* create the capture info dialog */
+/** Create the capture info dialog */
 extern void capture_info_create(
 capture_info    *cinfo,
 gchar           *iface);
 
-/* Update the capture info counters in the dialog */
+/** Update the capture info counters in the dialog */
 extern void capture_info_update(
 capture_info    *cinfo);
 
-/* destroy the capture info dialog again */
+/** Destroy the capture info dialog again */
 extern void capture_info_destroy(
 capture_info    *cinfo);
 
 
 #endif /* HAVE_LIBPCAP */
 
-#define EMPTY_FILTER ""
 #endif /* capture.h */
index c4c57b85ce54b0feae8bdee70c0b0c141c1e9b85..dc08fdfbc358466212731b63612e5dc8aca8f466 100644 (file)
@@ -1,7 +1,7 @@
 ## Makefile for building ethereal.exe with Microsoft C and nmake
 ## Use: $(MAKE) /$(MAKEFLAGS) -f makefile.nmake
 #
-# $Id: Makefile.nmake,v 1.75 2004/05/31 13:42:17 ulfl Exp $
+# $Id: Makefile.nmake,v 1.76 2004/06/04 17:16:57 ulfl Exp $
 
 include ..\config.nmake
 
@@ -47,14 +47,24 @@ clean:
 distclean: clean
        rm -f ethereal-tap-register.c
 
+# convert doxygen.cfg to doxygen.tmp with stamped version info
 doxygen.tmp: ..\config.nmake doxygen.cfg
+!IFDEF DOXYGEN
        sed -e s/@VERSION@/$(VERSION)/ \
            < doxygen.cfg > $@
+!ENDIF
 
 doxygen-run:
 !IFDEF DOXYGEN
        $(DOXYGEN) doxygen.tmp
 !ENDIF
 
-doxygen: doxygen.tmp doxygen-run
+# MS html help conpiler hhc returns 1 on success, but as nmake expects 0 it would stop here.
+# the prepended -1 will raise the accepted error levels of nmake, so it will continue
+doxygen.chm:
+!IFDEF HHC
+       -1 $(HHC) html\index.hhp
+!ENDIF
+
+doxygen: doxygen.tmp doxygen-run doxygen.chm
 
index 8516a57346a3860456289c7c0bf03d95fd7650f3..76f0bf8566571a95d2e869bad9fc8829e0002be3 100644 (file)
@@ -1,7 +1,7 @@
 /* dlg_utils.h
  * Declarations of utilities to use when constructing dialogs
  *
- * $Id: dlg_utils.h,v 1.19 2004/06/01 20:28:04 ulfl Exp $
+ * $Id: dlg_utils.h,v 1.20 2004/06/04 17:16:57 ulfl Exp $
  *
  * Ethereal - Network traffic analyzer
  * By Gerald Combs <gerald@ethereal.com>
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  */
 
+/** @defgroup dialog_group Dialogs
+ *
+ * Dialogs are specially created windows and are related to their parent windows (usually the main window). 
+ * See: @ref howto_window_page for details.
+ *
+ * @section normal_dialogs Normal dialogs 
+ *
+ * Normal dialogs are created using dlg_window_new().
+ *
+ * - "About" about_ethereal_cb()
+ * - "Capture Options" capture_prep()
+ * - "Capture" capture_info_create()
+ * - "Interface Options" ifopts_edit_cb()
+ * - "Coloring Rules" colorize_dialog_new()
+ * - "Edit Color Filter" edit_color_filter_dialog_new()
+ * - "Compute DCE-RPC SRT statistics" gtk_dcerpcstat_cb()
+ * - "Decode As: Show" decode_show_cb()
+ * - "Decode As" decode_as_cb()
+ * - "Filter Expression" dfilter_expr_dlg_new()
+ * - "Compute Fibre Channel Service Response Time statistics" gtk_fcstat_cb()
+ * - "Filter" (display and capture) filter_dialog_new()
+ * - "Find Packet" find_frame_cb()
+ * - "Follow TCP stream" follow_stream_cb()
+ * - "Go To Packet" goto_frame_cb()
+ * - "Compute LDAP Service Response Time statistics" gtk_ldapstat_cb()
+ * - "Preferences" tools_plugins_cmd_cb()
+ * - "Print" / "Export" open_print_dialog()
+ * - "Progress" create_progress_dlg()
+ * - "Enabled Protocols" proto_cb()
+ * - "Compute ONC-RPC SRT statistics" gtk_rpcstat_cb()
+ * - "RTP Streams" rtpstream_dlg_create()
+ * - "Simple Dialog" display_simple_dialog()
+ * - "Compute SMB SRT statistics" gtk_smbstat_cb()
+ * - "Compute ..." gtk_tap_dfilter_dlg_cb()
+ * - "Tcp Graph" create_drawing_area()
+ * - "Tcp Graph Control" control_panel_create()
+ * - "Help for TCP graphing" callback_create_help()
+ * - "Tcp Graph Magnify" magnify_create()
+ *
+ * @section file_sel_dialogs File selection dialogs 
+ *
+ * File selection dialogs are created using file_selection_new().
+ *
+ * - "Browse" file_selection_browse()
+ * - "Open Capture File" file_open_cmd()
+ * - "Save Capture File As" file_save_as_cmd()
+ * - "Import Color Filters" file_color_import_cmd_cb()
+ * - "Export Color Filters" file_color_export_cmd_cb()
+ * - "Save TCP Follow Stream As" follow_save_as_cmd_cb()
+ * - "Export Selected Packet Bytes" savehex_cb()
+ * - "Save Data As CSV" save_csv_as_cb()
+ * - "Save Payload As ..." on_save_bt_clicked()
+ * - "Save selected stream in rtpdump" rtpstream_on_save()
+ * 
+ */
+
 /** @file
- * Utilities for dialog boxes, depending on the window functions in 
- * ui_util.h. These dialog box windows will be related to Ethereal's main 
- * window. See window_new() and others in ui_util.h for further explanation 
- * of dialogs and windows in Ethereal.
+ * Utilities for dialog boxes. Depending on the window functions in 
+ * ui_util.h, see: @ref howto_window_page for details.
+ * @ingroup dialog_group
  */
 
 #ifndef __DLG_UTILS_H__
 #define __DLG_UTILS_H__
 
-/** Get the latest opened directory.
- *
- * @return the dirname
- */
-char *get_last_open_dir(void);
-
-/** Set the latest opened directory.
- *  Will already be done when using file_selection_new().
- *
- * @param dirname the dirname
- */
-void set_last_open_dir(char *dirname);
-
 
 /** Create a dialog box window that belongs to Ethereal's main window.
  * If you want to create a window, use window_new() instead. 
@@ -101,6 +143,20 @@ extern void file_selection_set_extra_widget(GtkWidget *fs, GtkWidget *extra);
 extern void
 file_selection_browse(GtkWidget *file_bt, GtkWidget *file_te, const char *title, file_selection_action_t action);
 
+/** Get the latest opened directory.
+ *
+ * @return the dirname
+ */
+extern char *get_last_open_dir(void);
+
+/** Set the latest opened directory.
+ *  Will already be done when using file_selection_new().
+ *
+ * @param dirname the dirname
+ */
+extern void set_last_open_dir(char *dirname);
+
+
 /** 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.
  *
index 41869873693d59c5d4332a7950754335d32dfa96..0eb9026f0d3ae29a4033f5ad8934482ce9fefd2c 100644 (file)
@@ -1,7 +1,7 @@
 # The PROJECT_NAME tag is a single word (or a sequence of words surrounded 
 # by quotes) that should identify the project.
 
-PROJECT_NAME           = Ethereal-Gtk
+PROJECT_NAME           = Ethereal-GTK
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number. 
 # This could be handy for archiving the generated documentation or 
@@ -21,7 +21,7 @@ OUTPUT_DIRECTORY       =
 # directories like "/usr/src/myproject". Separate the files or directories 
 # with spaces.
 
-INPUT                  = 
+INPUT                  = .
 
 # If the value of the INPUT tag contains directories, you can use the 
 # FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp 
index 9e1df4ddf74d9ae6fd81d678f57f9be563e3ede9..4d8bf522c9b22da829faf0d3c2470b3fc3895204 100644 (file)
@@ -1,7 +1,7 @@
 /* gtkglobals.h
  * GTK-related Global defines, etc.
  *
- * $Id: gtkglobals.h,v 1.26 2004/06/02 07:12:10 ulfl Exp $
+ * $Id: gtkglobals.h,v 1.27 2004/06/04 17:16:57 ulfl Exp $
  *
  * Ethereal - Network traffic analyzer
  * By Gerald Combs <gerald@ethereal.com>
 #ifndef __GTKGLOBALS_H__
 #define __GTKGLOBALS_H__
 
+/** @mainpage GTK subsystem
+ *
+ * @section intro Introduction
+ *
+ * Ethereal uses GTK (the Gimp ToolKit) as it's user interface toolkit.
+ *
+ * See Modules for a list of submodules.
+ *
+ * Additional info pages:
+ *
+ * - @ref howto_window_page
+ *
+ */
+
+/** @defgroup helpers_group General purpose helpers
+ *
+ * There are some general purpose helper files.
+ */
+
 /** @file
- *  GTK globals like the main application window.
+ *  GTK global definitions. For example a pointer to the main application window.
+ *  @ingroup helpers_group
  */
 
 /** application window */
index cbbac76103c55a9b07c501aa876d7a1d602884d8..26ee1e48ef8336e915d6e5d6cf5d936c9155fa42 100644 (file)
@@ -1,7 +1,7 @@
 /* main.h
  * Global defines, etc.
  *
- * $Id: main.h,v 1.50 2004/06/01 17:33:36 ulfl Exp $
+ * $Id: main.h,v 1.51 2004/06/04 17:16:57 ulfl Exp $
  *
  * Ethereal - Network traffic analyzer
  * By Gerald Combs <gerald@ethereal.com>
 
 #include "globals.h"
 
+/** @defgroup main_window_group Main window
+ * The main window has the following submodules:
+   @dot
+  digraph main_dependencies {
+      node [shape=record, fontname=Helvetica, fontsize=10];
+      main [ label="main window" URL="\ref main.h"];
+      menu [ label="menubar" URL="\ref menu.h"];
+      toolbar [ label="toolbar" URL="\ref toolbar.h"];
+      packet_list [ label="packet list pane" URL="\ref packet_list.h"];
+      proto_draw [ label="packet details & bytes panes" URL="\ref proto_draw.h"];
+      recent [ label="recent user settings" URL="\ref recent.h"];
+      main -> menu [ arrowhead="open", style="solid" ];
+      main -> toolbar [ arrowhead="open", style="solid" ];
+      main -> packet_list [ arrowhead="open", style="solid" ];
+      main -> proto_draw [ arrowhead="open", style="solid" ];
+      main -> recent [ arrowhead="open", style="solid" ];
+  }
+  @enddot
+ */
+
 /** @file
- *  Various functions provided by main.c
+ *  The main window, filter toolbar, program start/stop and a lot of other things
+ *  @ingroup main_window_group
+ *  @ingroup windows_group
  */
 
+
 /** User requested "Zoom In" by menu or toolbar.
  *
  * @param widget parent widget (unused)
index ece8129e14fa1c1bb4f838464602248f4c98fdde..16d1c5d73313bd27f280509238f149b9e0f280af 100644 (file)
@@ -1,7 +1,7 @@
 /* menu.h
  * Menu definitions
  *
- * $Id: menu.h,v 1.19 2004/06/01 21:56:04 ulfl Exp $
+ * $Id: menu.h,v 1.20 2004/06/04 17:16:57 ulfl Exp $
  *
  * Ethereal - Network traffic analyzer
  * By Gerald Combs <gerald@ethereal.com>
@@ -30,7 +30,8 @@ extern "C" {
 #endif /* __cplusplus */
 
 /** @file
- *  Various functions provided by menu.c
+ *  Menubar and context menus.
+ *  @ingroup main_window_group
  */
 
 /** Write all recent capture filenames to the user's recent file.
index 069a70d70540b17339b56af35bbade50552b0521..fed62a8c08c88f2161ee2a0b96d9bbc2b8b85213 100644 (file)
@@ -1,7 +1,7 @@
 /* packet_list.h
  * Declarations of GTK+-specific routines for managing the packet list.
  *
- * $Id: packet_list.h,v 1.3 2004/06/02 18:44:10 ulfl Exp $
+ * $Id: packet_list.h,v 1.4 2004/06/04 17:16:58 ulfl Exp $
  *
  * Ethereal - Network traffic analyzer
  * By Gerald Combs <gerald@ethereal.com>
@@ -26,7 +26,8 @@
 #define __PACKET_LIST_H__
 
 /** @file
- *  Main windows packet list.
+ *  Packet list pane.
+ *  @ingroup main_window_group
  */
 
 /** Create a new packet list.
index bca8e5e77d7f08db2e48e962183ff53e046d3416..20e5b5da5c6af9407df144c201b0c40303f2c478 100644 (file)
@@ -1,7 +1,7 @@
 /* proto_draw.h
  * Definitions for GTK+ packet display structures and routines
  *
- * $Id: proto_draw.h,v 1.27 2004/06/03 21:46:27 guy Exp $
+ * $Id: proto_draw.h,v 1.28 2004/06/04 17:16:58 ulfl Exp $
  *
  * Ethereal - Network traffic analyzer
  * By Gerald Combs <gerald@ethereal.com>
@@ -27,6 +27,7 @@
 
 /** @file
  *  Packet tree and details panes.
+ *  @ingroup main_window_group
  */
 
 /** Get the current text notebook page of the packet details notebook.
index 34bcde560ae8940517127549eb0334ebf4aaf995..3c6d8e74b5b9a0deaa70a4ecc5d80378c77d203c 100644 (file)
@@ -2,7 +2,7 @@
  * Definitions for recent "preference" handling routines
  * Copyright 2004, Ulf Lamping <ulf.lamping@web.de>
  *
- * $Id: recent.h,v 1.10 2004/06/02 22:13:04 ulfl Exp $
+ * $Id: recent.h,v 1.11 2004/06/04 17:16:58 ulfl Exp $
  *
  * Ethereal - Network traffic analyzer
  * By Gerald Combs <gerald@ethereal.com>
@@ -30,6 +30,7 @@
 
 /** @file
  *  Recent user interface settings.
+ *  @ingroup main_window_group
  */
 
 /** ???. */
index 62546134fdc0a0ff412b8e413d1b2289cb8fcbb6..b6833c4b4d3f488951e34639b151076b432ebe1e 100644 (file)
@@ -2,7 +2,7 @@
  * Definitions for toolbar utility routines
  * Copyright 2003, Ulf Lamping <ulf.lamping@web.de>
  *
- * $Id: toolbar.h,v 1.8 2004/06/01 17:33:37 ulfl Exp $
+ * $Id: toolbar.h,v 1.9 2004/06/04 17:16:58 ulfl Exp $
  *
  * Ethereal - Network traffic analyzer
  * By Gerald Combs <gerald@ethereal.com>
@@ -28,6 +28,7 @@
 
 /** @file
  *  The main toolbar.
+ *  @ingroup main_window_group
  */
 
 /** Create the main toolbar.
index fc2e876582a49d72764fb2c08fb4da1b23364273..55800f38441eab09e6e3265d223985a54e0c6c6e 100644 (file)
@@ -1,7 +1,7 @@
 /* ui_util.h
  * Definitions for UI utility routines
  *
- * $Id: ui_util.h,v 1.13 2004/06/01 20:28:05 ulfl Exp $
+ * $Id: ui_util.h,v 1.14 2004/06/04 17:16:58 ulfl Exp $
  *
  * Ethereal - Network traffic analyzer
  * By Gerald Combs <gerald@ethereal.com>
 #ifndef __GTKGUIUI_UTIL_H__
 #define __GTKGUIUI_UTIL_H__
 
-
-/** @file 
- * Utilities for Windows and other user interface functions.
+/** @defgroup windows_group Windows
  *
- * Some words about windows / dialogs.
- * 
- * delete event: the window managers "X" (e.g. upper right edge) of the window 
- *   was clicked, default handler will call gtk_widget_destroy()
- * destroy event: everything is already gone, only cleanup of left over ressources
- *   can/should be done now
+ * There are the following toplevel windows:
  *
- * Hint: don't use WIDGET_SET_SIZE() to set the size of a window,
- * use gtk_window_set_default_size() for that purpose!
+ * - @ref main_window_group
+ * - Statistic Windows (several different statistic windows)
  *
- * be sure, to call window_present() / window_destroy() appropriately, if you 
- *   want to have size and position handled by ui_util
+ * See: @ref howto_window_page for details.
+ * 
+ */
+
+/** @page howto_window_page How to develop a window / dialog
  *
- * A typical window / dialog will be created by:
+ * Windows and dialogs are related to each other. Dialogs are special kind of windows, but they behave
+ * slightly different. Dialogs stick on it's parent window, normal windows will be much more independant
+ * from it's parent window. Dialogs should be used to ask or note the user something, while windows should
+ * show data independantly from the main window.
+ * Dialogs are created by calling dlg_window_new() which in turn will call window_new().
+ * After that, dialogs can be developed the same way as windows, all window related functions in ui_util.h 
+ * can be used for both.
  *
- * window_new() will create a new window with default position and size,
- *   use dlg_window_new() if you need a dialog (transient to the main window)
+ * @section window_create Create a window
  *
- * gtk_window_set_default_size() to set the default size of the window, only
- *   needed, if the initial size is not appropriate, e.g. a scrolled_window_new() is used
- *   be sure the given is larger than the initial size, otherwise might get clipped content on GTK1
+ * A typical window / dialog will be created by the following calls:
  *
- * SIGNAL_CONNECT(my_win, "destroy", my_destroy_cb, NULL) callback, if some cleanup needs to be 
+ * - window_new() will create a new window with default position and size,
+ *   use dlg_window_new() if you need a dialog (transient to the main window)
+ * - gtk_window_set_default_size() to set the default size of the window. Only
+ *   needed, if the initial size is not appropriate, e.g. when a scrolled_window_new() is used.
+ *   Be sure that the given size is larger than the initial size, otherwise the window might
+ *   clip the content (at least on GTK1)
+ * - SIGNAL_CONNECT(my_win, "destroy", my_destroy_cb, NULL) callback, if some cleanup needs to be 
  *   done after the window is destroyed, e.g. free up memory, or set the window pointer
  *   of a singleton window (only one instance allowed, e.g. about dialog) back to zero
+ * - create and fill in the content and button widgets
+ * - gtk_widget_show_all() shows all the widgets in the window
+ * - window_present() present the window on screen and 
+ *   (if available) set previously saved position and size
  *
- * create and fill in the content and button widgets
+ * @section window_events Events
  *
- * gtk_widget_show_all() show all the widgets in the window
+ * The following events are usually interesting:
  *
- * window_present() present the window on screen and 
- *   (if available) set previously saved position and size
+ * - "delete_event": the window managers "X" (e.g. upper right edge) of the window 
+ *   was clicked, default handler will call gtk_widget_destroy()
+ * - "destroy": everything is already gone, only cleanup of left over ressources
+ *   can/should be done now
+ *
+ * @section window_hints Hints
  *
- * if you want to save size and position, be sure to call window_destroy() instead of only 
+ * If you want to save size and position, be sure to call window_destroy() instead of only 
  *   gtk_widget_destroy(), so you will probably have to SIGNAL_CONNECT to the "delete_event"!
+ *
+ * Don't use WIDGET_SET_SIZE() to set the size of a window,
+ * use gtk_window_set_default_size() for that purpose!
+ *
+ * Be sure to call window_present() / window_destroy() appropriately, if you 
+ *   want to have size and position of the window handled by ui_util.
+ *
+ */
+
+/** @file 
+ * Utilities for Windows and other user interface functions. See: @ref howto_window_page for details.
+ * @ingroup dialog_group
+ * @ingroup windows_group
  */
 
+/** @name Window Functions
+ *  @todo Move these window functions to a new file win_utils.h?
+ *  @{ */
+
 /** Create a new window with the Ethereal icon. 
  *  If you want to create a dialog, use dlg_window_new() instead. 
  *
@@ -178,6 +208,8 @@ extern void window_geom_recent_read_pair(const char *name, const char *key, cons
  */
 void reactivate_window(GtkWidget *win);
 
+/** @} */
+
 /** Create a GtkScrolledWindow, set its scrollbar placement appropriately,
  *  and remember it.
  *