[gdl] Document GdlDockMaster

[Sebastien Granjoux <sgranjoux src gnome org>]

commit c631b6eab2599dc20f5f075d418a7ce450f34a55
Author: SÃbastien Granjoux <seb sfo free fr>
Date:   Sat May 19 19:55:54 2012 +0200

    Document GdlDockMaster

 gdl/gdl-dock-master.c |   70 +++++++++++++++++++++++++++++++++++++++++++++++++
 gdl/gdl-dock-master.h |   20 ++++++++++---
 2 files changed, 85 insertions(+), 5 deletions(-)
---
diff --git a/gdl/gdl-dock-master.c b/gdl/gdl-dock-master.c
index 039d210..222704e 100644
--- a/gdl/gdl-dock-master.c
+++ b/gdl/gdl-dock-master.c
@@ -36,6 +36,20 @@
 #include "libgdlmarshal.h"
 #include "libgdltypebuiltins.h"
 
+/**
+ * SECTION:gdl-dock-master
+ * @title: GdlDockMaster
+ * @short_description: Manage all dock widgets
+ * @stability: Internal
+ *
+ * For the toplevel docks to be able to interact with each other, when the user
+ * drags items from one place to another, they're all kept in a user-invisible
+ * and automatic object called the master. To participate in docking operations
+ * every #GdlDockObject must have the same master, the binding to the master is
+ * done automatically.  The master also keeps track of the manual items,
+ * mostly those created with gdl_dock_*_new functions which are in the dock.
+ */
+
 /* ----- Private prototypes ----- */
 
 static void     gdl_dock_master_class_init    (GdlDockMasterClass *klass);
@@ -756,6 +770,13 @@ item_notify_cb (GdlDockObject *object,
 
 /* ----- Public interface ----- */
 
+/**
+ * gdl_dock_master_add:
+ * @master: a #GdlDockMaster
+ * @object: a #GdlDockObject
+ *
+ * Add a new dock widget to the master.
+ */
 void
 gdl_dock_master_add (GdlDockMaster *master,
                      GdlDockObject *object)
@@ -843,6 +864,13 @@ gdl_dock_master_add (GdlDockMaster *master,
     }
 }
 
+/**
+ * gdl_dock_master_remove:
+ * @master: a #GdlDockMaster
+ * @object: a #GdlDockObject
+ *
+ * Remove one dock widget from the master.
+ */
 void
 gdl_dock_master_remove (GdlDockMaster *master,
                         GdlDockObject *object)
@@ -878,6 +906,14 @@ gdl_dock_master_remove (GdlDockMaster *master,
     g_object_unref (master);
 }
 
+/**
+ * gdl_dock_master_foreach:
+ * @master: a #GdlDockMaster
+ * @function: the function to call with each element's data
+ * @user_data: user data to pass to the function
+ *
+ * Call @function on each dock widget of the master.
+ */
 void
 gdl_dock_master_foreach (GdlDockMaster *master,
                          GFunc          function,
@@ -895,6 +931,16 @@ gdl_dock_master_foreach (GdlDockMaster *master,
     g_hash_table_foreach (master->dock_objects, _gdl_dock_master_foreach, &data);
 }
 
+/**
+ * gdl_dock_master_foreach_toplevel:
+ * @master: a #GdlDockMaster
+ * @include_controller: %TRUE to include the controller
+ * @function: the function to call with each element's data
+ * @user_data: user data to pass to the function
+ *
+ * Call @function on each top level dock widget of the master, including or not
+ * the controller.
+ */
 void
 gdl_dock_master_foreach_toplevel (GdlDockMaster *master,
                                   gboolean       include_controller,
@@ -913,6 +959,15 @@ gdl_dock_master_foreach_toplevel (GdlDockMaster *master,
     }
 }
 
+/**
+ * gdl_dock_master_get_object:
+ * @master: a #GdlDockMaster
+ * @nick_name: the name of the dock widget.
+ *
+ * Looks for a #GdlDockObject named @nick_name.
+ *
+ * Returns: A #GdlDockObject named @nick_name or %NULL if it does not exist.
+ */
 GdlDockObject *
 gdl_dock_master_get_object (GdlDockMaster *master,
                             const gchar   *nick_name)
@@ -929,6 +984,14 @@ gdl_dock_master_get_object (GdlDockMaster *master,
     return found ? GDL_DOCK_OBJECT (found) : NULL;
 }
 
+/**
+ * gdl_dock_master_get_controller:
+ * @master: a #GdlDockMaster
+ *
+ * Retrieves the #GdlDockObject acting as the controller.
+ *
+ * Returns: A #GdlDockObject.
+ */
 GdlDockObject *
 gdl_dock_master_get_controller (GdlDockMaster *master)
 {
@@ -937,6 +1000,13 @@ gdl_dock_master_get_controller (GdlDockMaster *master)
     return master->controller;
 }
 
+/**
+ * gdl_dock_master_set_controller:
+ * @master: a #GdlDockMaster
+ * @new_controller: a #GdlDockObject
+ *
+ * Set a new controller. The controller must be a top level #GdlDockObject.
+ */
 void
 gdl_dock_master_set_controller (GdlDockMaster *master,
                                 GdlDockObject *new_controller)
diff --git a/gdl/gdl-dock-master.h b/gdl/gdl-dock-master.h
index 82ace7a..4cf5cd7 100644
--- a/gdl/gdl-dock-master.h
+++ b/gdl/gdl-dock-master.h
@@ -1,4 +1,4 @@
-/* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*- 
+/* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
  *
  * gdl-dock-master.h - Object which manages a dock ring
  *
@@ -28,7 +28,6 @@
 #include <gtk/gtk.h>
 #include <gdl/gdl-dock-object.h>
 
-
 G_BEGIN_DECLS
 
 /* standard macros */
@@ -44,6 +43,17 @@ typedef struct _GdlDockMaster        GdlDockMaster;
 typedef struct _GdlDockMasterClass   GdlDockMasterClass;
 typedef struct _GdlDockMasterPrivate GdlDockMasterPrivate;
 
+/**
+ * GdlSwitcherStyle:
+ * @GDL_SWITCHER_STYLE_TEXT: Tabs display only text labels.
+ * @GDL_SWITCHER_STYLE_ICON: Tabs display only icons.
+ * @GDL_SWITCHER_STYLE_BOTH: Tabs display text and icons.
+ * @GDL_SWITCHER_STYLE_TOOLBAR: Same as @GDL_SWITCHER_STYLE_BOTH.
+ * @GDL_SWITCHER_STYLE_TABS: Tabs display like notebook tabs.
+ * @GDL_SWITCHER_STYLE_NONE: Do not display tabs.
+ *
+ * Used to customize the appearance of the tabs in #GdlDockNotebook.
+ */
 typedef enum {
     GDL_SWITCHER_STYLE_TEXT,
     GDL_SWITCHER_STYLE_ICON,
@@ -59,9 +69,9 @@ struct _GdlDockMaster {
     GHashTable           *dock_objects;
     GList                *toplevel_docks;
     GdlDockObject        *controller;      /* GUI root object */
-    
+
     gint                  dock_number;     /* for toplevel dock numbering */
-    
+
     GdlDockMasterPrivate *priv;
 };
 
@@ -78,7 +88,7 @@ struct _GdlDockMasterClass {
         GDL_DOCK_MASTER (GDL_DOCK_OBJECT (object)->master) : NULL)
 
 /* public interface */
- 
+
 GType          gdl_dock_master_get_type         (void);
 
 void           gdl_dock_master_add              (GdlDockMaster *master,