[Gnucash-changes] Add doxygen comments.

[David Hampton]

Log Message:
-----------
Add doxygen comments.

Tags:
----
gnucash-gnome2-dev

Modified Files:
--------------
    gnucash/src/gnome:
        gnc-plugin.c
        gnc-plugin.h

Revision Data
-------------
Index: gnc-plugin.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/gnome/Attic/gnc-plugin.h,v
retrieving revision 1.1.2.9
retrieving revision 1.1.2.10
diff -Lsrc/gnome/gnc-plugin.h -Lsrc/gnome/gnc-plugin.h -u -r1.1.2.9 -r1.1.2.10
--- src/gnome/gnc-plugin.h
+++ src/gnome/gnc-plugin.h
@@ -22,6 +22,15 @@
  * Boston, MA  02111-1307,  USA       gnu at gnu.org
  */
 
+/** @addtogroup GUI
+    @{ */
+/** @addtogroup Wwindow plugin functions.
+    @{ */
+/** @file gnc-plugin.h
+    @brief Functions for adding plugins to a Gnucash window.
+    @author Copyright (C) 2002 David Hampton <hampton at employees.org>
+*/
+
 #ifndef __GNC_PLUGIN_H
 #define __GNC_PLUGIN_H
 
@@ -67,18 +76,59 @@
 } GncPluginClass;
 
 /* function prototypes */
-GType                 gnc_plugin_get_type        (void);
 
-void                  gnc_plugin_add_to_window   (GncPlugin *plugin,
-					          GncMainWindow *window,
-					          GQuark type);
-void                  gnc_plugin_remove_from_window (GncPlugin *plugin,
-					             GncMainWindow *window,
-					             GQuark type);
-
-GncPluginPage        *gnc_plugin_create_page     (GncPlugin *plugin,
-						  const gchar *uri);
-const gchar          *gnc_plugin_get_name (GncPlugin *plugin);
+/** Get the type of a gnc window plugin.
+ *
+ *  @return A GType.
+ */
+GType gnc_plugin_get_type (void);
+
+
+/** Add the specified plugin from the specified window.  This function
+ *  will add the page's user interface from the window, set up gconf
+ *  notifications if the page uses gconf, and call the plugin to
+ *  perform any plugin specific actions.
+ *
+ *  @param plugin The plugin to be added.
+ *
+ *  @param window Add the plugin to this window.
+ *
+ *  @param type An identifier for the type of window specified.
+ */
+void gnc_plugin_add_to_window (GncPlugin *plugin,
+			       GncMainWindow *window,
+			       GQuark type);
+
+
+/** Remove the specified plugin from the specified window.  This
+ *  function will call the plugin to perform any plugin specific
+ *  actions, remove any gconf notifications that were set up for the
+ *  page, and remove the page's user interface from the window.
+ *
+ *  @param plugin The plugin to be removed.
+ *
+ *  @param window The window the plugin should be removed from.
+ *
+ *  @param type An identifier for the type of window specified.
+ */
+void gnc_plugin_remove_from_window (GncPlugin *plugin,
+				    GncMainWindow *window,
+				    GQuark type);
+
+
+GncPluginPage *gnc_plugin_create_page (GncPlugin *plugin,
+				       const gchar *uri);
+
+
+/** Retrieve the name of a plugin.
+ *
+ *  @param plugin The plugin whose name should be returned.
+ *
+ *  @return  short_labels A pointer to a data structure containing
+ *  [action name, label string] string pairs.
+ */
+const gchar *gnc_plugin_get_name (GncPlugin *plugin);
+
 
 typedef struct {
   const char *action_name;
@@ -100,14 +150,14 @@
 
 
 /** Update a property on a set of existing GtkActions.  This function
- *  can be easily used to make a llist of actions visible, invisible,
+ *  can be easily used to make a list of actions visible, invisible,
  *  sensitive, or insensitive.
  *
  *  @param action_group The group of all actions associated with a
  *  plugin or plugin page.  All actions to be modified must be
  *  contained in this group.
  *
- *  @param action_names A null terminated list of actions names that
+ *  @param action_names A NULL terminated list of actions names that
  *  should modified.
  *
  *  @param property_name The property name to be changed on the
@@ -144,3 +194,6 @@
 G_END_DECLS
 
 #endif /* __GNC_PLUGIN_H */
+
+/** @} */
+/** @} */
Index: gnc-plugin.c
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/gnome/Attic/gnc-plugin.c,v
retrieving revision 1.1.2.10
retrieving revision 1.1.2.11
diff -Lsrc/gnome/gnc-plugin.c -Lsrc/gnome/gnc-plugin.c -u -r1.1.2.10 -r1.1.2.11
--- src/gnome/gnc-plugin.c
+++ src/gnome/gnc-plugin.c
@@ -41,6 +41,9 @@
 	gpointer dummy;
 };
 
+
+/** Get the type of a gnc window plugin.
+ */
 GType
 gnc_plugin_get_type (void)
 {
@@ -67,6 +70,16 @@
 	return gnc_plugin_type;
 }
 
+
+/** Initialize the class for the new gnucash plugin object.  This will
+ *  set up any function pointers that override functions in the parent
+ *  class, and also installs the proprieties that are unique to this
+ *  class.
+ *
+ *  @param klass The new class structure created by the object system.
+ *
+ *  @internal
+ */
 static void
 gnc_plugin_class_init (GncPluginClass *klass)
 {
@@ -76,6 +89,15 @@
 	gobject_class->finalize = gnc_plugin_finalize;
 }
 
+
+/** Initialize a new instance of a gnucash plugin object.  This
+ *  function allocates and initializes the object private storage
+ *  space.
+ *
+ *  @param view The new object instance created by the object system.
+ *
+ *  @internal
+ */
 static void
 gnc_plugin_init (GncPlugin *plugin_page)
 {
@@ -84,6 +106,17 @@
 	priv = plugin_page->priv = g_new0 (GncPluginPrivate, 1);
 }
 
+
+/** Finalize the gnucash plugin object.  This function is called from
+ *  the G_Object level to complete the destruction of the object.  It
+ *  should release any memory not previously released by the destroy
+ *  function (i.e. the private data structure), then chain up to the
+ *  parent's destroy function.
+ *
+ *  @param object The object being destroyed.
+ *
+ *  @internal
+ */
 static void
 gnc_plugin_finalize (GObject *object)
 {
@@ -100,6 +133,11 @@
 }
 
 
+/** Add the specified plugin from the specified window.  This function
+ *  will add the page's user interface from the window, set up gconf
+ *  notifications if the page uses gconf, and call the plugin to
+ *  perform any plugin specific actions.
+ */
 void
 gnc_plugin_add_to_window (GncPlugin *plugin,
 			  GncMainWindow *window,
@@ -142,6 +180,12 @@
 	LEAVE ("");
 }
 
+
+/*  Remove the specified plugin from the specified window.  This
+ *  function will call the plugin to perform any plugin specific
+ *  actions, remove any gconf notifications that were set up for the
+ *  page, and remove the page's user interface from the window.
+ */
 void
 gnc_plugin_remove_from_window (GncPlugin *plugin,
 			       GncMainWindow *window,
@@ -182,6 +226,7 @@
 	LEAVE ("");
 }
 
+
 GncPluginPage *
 gnc_plugin_create_page (GncPlugin *plugin,
 			const gchar *uri)
@@ -193,6 +238,9 @@
 	return GNC_PLUGIN_GET_CLASS (plugin)->create_page (plugin, uri);
 }
 
+
+/** Retrieve the name of a plugin.
+ */
 const gchar *
 gnc_plugin_get_name (GncPlugin *plugin)
 {