doxygen

diff --git a/disobedience/client.c b/disobedience/client.c
index 506212bb3bcadad4465c417cdf1aae8be5dc9c3f..8539221c11dc69440c21479a9d06276848dc34c1 100644 (file)
--- a/disobedience/client.c
+++ b/disobedience/client.c
@@ -1,6 +1,6 @@
 /*
  * This file is part of DisOrder.
 /*
  * 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
  *
  * 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 c3acca7e51059577fab8b44bf10f99f68ff6e3c5..09e8daf7f18d694c5012ebf38159643b8c7702ef 100644 (file)
--- a/disobedience/disobedience.h
+++ b/disobedience/disobedience.h
@@ -17,6 +17,9 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  * USA
  */
  * 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
 
 #ifndef DISOBEDIENCE_H
 #define DISOBEDIENCE_H


@@ -56,6 +59,12 @@
 struct queuelike;
 struct choosenode;
 
 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,
 struct callbackdata {
   void (*onerror)(struct callbackdata *cbd,
                   int code,


@@ -68,6 +77,11 @@ struct callbackdata {
   } u;
 };
 
   } 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);
 struct tabtype {
   int (*properties_sensitive)(GtkWidget *tab);
   int (*selectall_sensitive)(GtkWidget *tab);

diff --git a/disobedience/menu.c b/disobedience/menu.c
index 3347a51304a4f7806409deef0ea26f71418a9522..ad79a9206931fe60d97a3618835ac804d0c5b2f7 100644 (file)
--- a/disobedience/menu.c
+++ b/disobedience/menu.c
@@ -17,6 +17,9 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  * USA
  */
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  * USA
  */

+/** @file disobedience/menu.c
+ * @brief Main menu
+ */

 
 #include "disobedience.h"
 
 
 #include "disobedience.h"
 


@@ -25,6 +28,10 @@ static GtkWidget *properties_widget;
 
 static void about_popup_got_version(void *v, const char *value);
 
 
 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) {
 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 */
 }
 
 /* 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) {
 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);
 }
 
   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) {
 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);
 }
 
   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),
 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));
 }
   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) {
 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);
 }
 
                            0);
 }
 

+/** @brief Callde when version arrives, displays about... popup */

 static void about_popup_got_version(void attribute((unused)) *v,
                                     const char *value) {
   GtkWidget *w;
 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);
 }
 
   gtk_widget_destroy(w);
 }
 

+/** @brief Create the menu bar widget */

 GtkWidget *menubar(GtkWidget *w) {
   static const GtkItemFactoryEntry entries[] = {
     { (char *)"/File", 0,  0, 0, (char *)"<Branch>", 0 },
 GtkWidget *menubar(GtkWidget *w) {
   static const GtkItemFactoryEntry entries[] = {
     { (char *)"/File", 0,  0, 0, (char *)"<Branch>", 0 },

diff --git a/disobedience/misc.c b/disobedience/misc.c
index d0caf3b8a5676b1f1b96caec09870a67a6b9a293..f87f4a0339c25c80121da97d2be2e70e7e67e735 100644 (file)
--- a/disobedience/misc.c
+++ b/disobedience/misc.c
@@ -17,6 +17,9 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  * USA
  */
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  * USA
  */

+/** @file disobedience/misc.c
+ * @brief Miscellaneous GTK+ interfacing stuff
+ */

 
 #include "disobedience.h"
 
 
 #include "disobedience.h"
 


@@ -26,6 +29,11 @@ WT(cached_image);
 
 /* Functions */
 
 
 /* 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);
 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;
 }
 
   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 };
 
 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;
 }
 
   return pb;
 }
 

+/** @brief Pop up an error message */

 void popup_error(const char *msg) {
   GtkWidget *w;
 
 void popup_error(const char *msg) {
   GtkWidget *w;