[gdl] Document GdlDockPlaceHolder

[Sebastien Granjoux <sgranjoux src gnome org>]

commit 9eb721696cc2887db979ed6508601405330d6932
Author: SÃbastien Granjoux <seb sfo free fr>
Date:   Sun Jul 1 17:19:26 2012 +0200

    Document GdlDockPlaceHolder

 gdl/gdl-dock-placeholder.c |   37 ++++++++++++++++++++++++++++++++++---
 1 files changed, 34 insertions(+), 3 deletions(-)
---
diff --git a/gdl/gdl-dock-placeholder.c b/gdl/gdl-dock-placeholder.c
index 7ef672f..24b9d4c 100644
--- a/gdl/gdl-dock-placeholder.c
+++ b/gdl/gdl-dock-placeholder.c
@@ -33,6 +33,17 @@
 #include "gdl-dock-master.h"
 #include "libgdltypebuiltins.h"
 
+/**
+ * SECTION:gdl-dock-placeholder
+ * @title: GdlDockPlaceHolder
+ * @short_description: A widget marking a docking place.
+ * @see_also:
+ * @stability: Unstable
+ *
+ * A dock placeholder is a widget allowing to keep track of a docking place.
+ * Unfortunately, all the details of the initial goal have been forgotten and
+ * the code has still some issues.
+ */
 
 #undef PLACEHOLDER_DEBUG
 
@@ -86,9 +97,9 @@ enum {
     PROP_NEXT_PLACEMENT,
     PROP_WIDTH,
     PROP_HEIGHT,
-	PROP_FLOATING,
-	PROP_FLOAT_X,
-	PROP_FLOAT_Y
+    PROP_FLOATING,
+    PROP_FLOAT_X,
+    PROP_FLOAT_Y
 };
 
 struct _GdlDockPlaceholderPrivate {
@@ -539,6 +550,19 @@ gdl_dock_placeholder_present (GdlDockObject *object,
 
 /* ----- Public interface ----- */ 
 								   
+/**
+ * gdl_dock_placeholder_new:
+ * @name: Unique name for identifying the dock object.
+ * @object: Corresponding #GdlDockObject
+ * @position: The position to dock a new item in @object
+ * @sticky: %TRUE if the placeholder move with the @object
+ * 
+ * Creates a new dock placeholder at @object place. This is a kind of marker
+ * allowing you to dock new items later at this place. It is not completely
+ * working though.
+ * 
+ * Returns: The newly created placeholder.
+ */
 GtkWidget * 
 gdl_dock_placeholder_new (const gchar     *name,
                           GdlDockObject    *object,
@@ -796,6 +820,13 @@ connect_host (GdlDockPlaceholder *ph,
 #endif
 }
 
+/**
+ * gdl_dock_placeholder_attach:
+ * @ph: The #GdlDockPlaceholder object
+ * @object: A new #GdlDockObject
+ * 
+ * Move the placeholder to the position of @object.
+ */
 void
 gdl_dock_placeholder_attach (GdlDockPlaceholder *ph,
                              GdlDockObject      *object)