From 2c34878904d76d323b4698fe705c5f9d002e65f8 Mon Sep 17 00:00:00 2001 Message-Id: <2c34878904d76d323b4698fe705c5f9d002e65f8.1714820490.git.mdw@distorted.org.uk> From: Mark Wooding Date: Mon, 1 Oct 2007 18:44:18 +0100 Subject: [PATCH] doxygen Organization: Straylight/Edgeware From: Richard Kettlewell --- disobedience/client.c | 2 +- disobedience/disobedience.h | 14 ++++++++++++++ disobedience/menu.c | 27 ++++++++++++++++++++++++++- disobedience/misc.c | 18 ++++++++++++++++++ 4 files changed, 59 insertions(+), 2 deletions(-) diff --git a/disobedience/client.c b/disobedience/client.c index 506212b..8539221 100644 --- a/disobedience/client.c +++ b/disobedience/client.c @@ -1,6 +1,6 @@ /* * This file is part of DisOrder. - * Copyright (C) 2006, 2007 Richard Kettlewell + * Copyright (C) 2006, 2007 Richard Kettlewell * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by diff --git a/disobedience/disobedience.h b/disobedience/disobedience.h index c3acca7..09e8daf 100644 --- a/disobedience/disobedience.h +++ b/disobedience/disobedience.h @@ -17,6 +17,9 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 * USA */ +/** @file disobedience/disobedience.h + * @brief Header file for Disobedience, the DisOrder GTK+ client + */ #ifndef DISOBEDIENCE_H #define DISOBEDIENCE_H @@ -56,6 +59,12 @@ struct queuelike; struct choosenode; +/** @brief Callback data structure + * + * This program is extremely heavily callback-driven. Rather than have + * numerous different callback structures we have a single one which can be + * interpreted adequately both by success and error handlers. + */ struct callbackdata { void (*onerror)(struct callbackdata *cbd, int code, @@ -68,6 +77,11 @@ struct callbackdata { } u; }; +/** @brief Per-tab callbacks + * + * Some of the options in the main menu depend on which tab is displayed, so we + * have some callbacks to set them appropriately. + */ struct tabtype { int (*properties_sensitive)(GtkWidget *tab); int (*selectall_sensitive)(GtkWidget *tab); diff --git a/disobedience/menu.c b/disobedience/menu.c index 3347a51..ad79a92 100644 --- a/disobedience/menu.c +++ b/disobedience/menu.c @@ -17,6 +17,9 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 * USA */ +/** @file disobedience/menu.c + * @brief Main menu + */ #include "disobedience.h" @@ -25,6 +28,10 @@ static GtkWidget *properties_widget; static void about_popup_got_version(void *v, const char *value); +/** @brief Called when the quit option is activated + * + * Just exits. + */ static void quit_program(gpointer attribute((unused)) callback_data, guint attribute((unused)) callback_action, GtkWidget attribute((unused)) *menu_item) { @@ -33,6 +40,11 @@ static void quit_program(gpointer attribute((unused)) callback_data, } /* TODO can we have a single parameterized callback for all these */ + +/** @brief Called when the select all option is activated + * + * Calls the per-tab select all function. + */ static void select_all(gpointer attribute((unused)) callback_data, guint attribute((unused)) callback_action, GtkWidget attribute((unused)) *menu_item) { @@ -43,6 +55,10 @@ static void select_all(gpointer attribute((unused)) callback_data, t->selectall_activate(tab); } +/** @brief Called when the track properties option is activated + * + * Calls the per-tab properties function. + */ static void properties_item(gpointer attribute((unused)) callback_data, guint attribute((unused)) callback_action, GtkWidget attribute((unused)) *menu_item) { @@ -53,6 +69,12 @@ static void properties_item(gpointer attribute((unused)) callback_data, t->properties_activate(tab); } +/** @brief Update menu state + * + * Determines option sensitivity according to the current tab and adjusts the + * widgets accordingly. Knows about @ref DISORDER_CONNECTED so the callbacks + * need not. + */ void menu_update(int page) { GtkWidget *tab = gtk_notebook_get_nth_page (GTK_NOTEBOOK(tabs), @@ -66,7 +88,8 @@ void menu_update(int page) { gtk_widget_set_sensitive(selectall_widget, t->selectall_sensitive(tab)); } - + +/** @brief Fetch version in order to display the about... popup */ static void about_popup(gpointer attribute((unused)) callback_data, guint attribute((unused)) callback_action, GtkWidget attribute((unused)) *menu_item) { @@ -78,6 +101,7 @@ static void about_popup(gpointer attribute((unused)) callback_data, 0); } +/** @brief Callde when version arrives, displays about... popup */ static void about_popup_got_version(void attribute((unused)) *v, const char *value) { GtkWidget *w; @@ -102,6 +126,7 @@ static void about_popup_got_version(void attribute((unused)) *v, gtk_widget_destroy(w); } +/** @brief Create the menu bar widget */ GtkWidget *menubar(GtkWidget *w) { static const GtkItemFactoryEntry entries[] = { { (char *)"/File", 0, 0, 0, (char *)"", 0 }, diff --git a/disobedience/misc.c b/disobedience/misc.c index d0caf3b..f87f4a0 100644 --- a/disobedience/misc.c +++ b/disobedience/misc.c @@ -17,6 +17,9 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 * USA */ +/** @file disobedience/misc.c + * @brief Miscellaneous GTK+ interfacing stuff + */ #include "disobedience.h" @@ -26,6 +29,11 @@ WT(cached_image); /* Functions */ +/** @brief Put scrollbars around a widget + * @param child Widget to surround + * @param widgetname Name for (both) widgets + * @return Scroll widget + */ GtkWidget *scroll_widget(GtkWidget *child, const char *widgetname) { GtkWidget *scroller = gtk_scrolled_window_new(0, 0); @@ -57,6 +65,15 @@ GtkWidget *scroll_widget(GtkWidget *child, return scroller; } +/** @brief Find an image + * @param name Relative path to image + * @return pixbuf containing image + * + * Images are cached so it's perfectly sensible to call this lots of times even + * for the same image. + * + * Images are searched for in @c pkgdatadir/static. + */ GdkPixbuf *find_image(const char *name) { static const struct cache_type image_cache_type = { INT_MAX }; @@ -76,6 +93,7 @@ GdkPixbuf *find_image(const char *name) { return pb; } +/** @brief Pop up an error message */ void popup_error(const char *msg) { GtkWidget *w; -- [mdw]