diff --git a/clutter/clutter-box.c b/clutter/clutter-box.c
index 2e886b617..0d497b397 100644
--- a/clutter/clutter-box.c
+++ b/clutter/clutter-box.c
@@ -13,7 +13,31 @@
  * SECTION:clutter-box
  * @short_description: Base class for layout containers
  *
- * FIXME
+ * #ClutterBox is a base class for containers which impose a specific layout
+ * on their children, unlike #ClutterGroup which is a free-form container.
+ *
+ * Layout containers are expected to move and size their children depending
+ * on a layout contract they establish per-class. For instance, a #ClutterHBox
+ * (a subclass of #ClutterBox) lays out its children along an imaginary
+ * horizontal line.
+ *
+ * All #ClutterBox<!-- -->es have a margin, which is decomposed in four
+ * components (top, right, bottom left) and a background color. Each child
+ * of a #ClutterBox has a packing type and a padding, decomposed like the
+ * margin. Actors can be packed using clutter_box_pack() and providing
+ * the packing type and the padding, or using clutter_box_pack_defaults()
+ * and setting a default padding with clutter_box_set_default_padding().
+ * A #ClutterBox implements the #ClutterContainer interface: calling
+ * clutter_container_add_actor() on a #ClutterBox will automatically invoke
+ * clutter_box_pack_defaults().
+ *
+ * Each child of a #ClutterBox has its packing information wrapped into the
+ * #ClutterBoxChild structure, which can be retrieved either using the
+ * clutter_box_query_child() or the clutter_box_query_nth_child() function.
+ *
+ * Subclasses of #ClutterBox must implement the ClutterBox::pack_child and
+ * ClutterBox::unpack_child virtual functions; these functions will be called
+ * when adding a child and when removing one, respectively.
  *
  * #ClutterBox is available since Clutter 0.4
  */
diff --git a/clutter/clutter-hbox.c b/clutter/clutter-hbox.c
index 8fc05b473..452d3a63b 100644
--- a/clutter/clutter-hbox.c
+++ b/clutter/clutter-hbox.c
@@ -15,7 +15,9 @@
  * SECTION:clutter-hbox
  * @short_description: Simple horizontal box
  *
- * FIXME
+ * A #ClutterHBox is a #ClutterBox which lays all its children horizontally.
+ *
+ * See #ClutterBox for more details.
  *
  * #ClutterHBox is available since Clutter 0.4.
  */
diff --git a/clutter/clutter-vbox.c b/clutter/clutter-vbox.c
index 86e44bfa2..f5e365f37 100644
--- a/clutter/clutter-vbox.c
+++ b/clutter/clutter-vbox.c
@@ -13,9 +13,11 @@
 
 /**
  * SECTION:clutter-vbox
- * @short_description: Simple horizontal box
+ * @short_description: Simple vertical box
  *
- * FIXME
+ * A #ClutterVBox is a #ClutterBox that lays out its children vertically.
+ *
+ * See #ClutterBox for more details.
  *
  * #ClutterVBox is available since Clutter 0.4.
  */