[gtkmm/gtkmm-3-4] Container: Slight improvements to the vfunc documentation.

[Murray Cumming <murrayc src gnome org>]

commit 2974fdddba0cc8dfca074fa8419944c569d73e6d
Author: Murray Cumming <murrayc murrayc com>
Date:   Mon May 28 21:45:08 2012 +0200

    Container: Slight improvements to the vfunc documentation.
    
    * gtk/src/container.hg:

 ChangeLog            |   16 +++++++++++++
 gtk/src/container.hg |   62 +++++++++++++++++++++++++++++++++++--------------
 2 files changed, 60 insertions(+), 18 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 05bc22d..2f7e3f7 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,19 @@
+2012-05-28  Murray Cumming  <murrayc murrayc com>
+
+	Container: Slight improvements to the vfunc documentation.
+
+	* gtk/src/container.hg:
+
+2012-05-28  Mark Vender <markv743 yahoo co uk>
+
+ 	Container: Document several rarely used virtual functions
+    
+	* gtk/src/container.hg: Add documentation for the following functions:
+	child_type(), forall(), composite_child(), [get|set]_child_property(). The
+	documentation comes from the C docs.
+    
+	Bug #670206.
+
 2012-04-19  Murray Cumming  <murrayc murrayc com>
 
 	Application: add_window(): Correct the documentation.
diff --git a/gtk/src/container.hg b/gtk/src/container.hg
index 43f4894..e215155 100644
--- a/gtk/src/container.hg
+++ b/gtk/src/container.hg
@@ -178,41 +178,67 @@ public:
 protected:
   _CTOR_DEFAULT()
 
-  /** Implements child_type(). The default implementation returns G_TYPE_NONE
+  /** Implements child_type().
+   *
+   * The default implementation returns G_TYPE_NONE
    */
   _WRAP_VFUNC(GType child_type() const, child_type)
 
-  /** Invokes callback on all children of the container. The callback is invoked
-   * also on children that are considered "internal" (implementation details of
-   * the container). "Internal" children generally weren't added by the user
-   * of the container, but were added by the container implementation itself.
+  /** Invokes a callback on all children of the container.
+   *
+   * The callback may optionally be invoked also on children that are considered 
+   * "internal" (implementation details of the container). "Internal" children 
+   * generally  weren't added by the user of the container, but were added by the 
+   * container implementation itself.
+   *
    * Most applications should use foreach(), rather than forall().
+   *
+   * @param include_internals
+   * @param callback A callback.
+   * @param callback_data Callback user data
    */
   _WRAP_VFUNC(void forall(gboolean include_internals, GtkCallback callback, gpointer callback_data), forall)
 
-  /** Returns the composite name of a child widget. Composite widgets are
-   * children of the container that are considered "internal" (implementation
-   * details of the container). "Internal" children generally weren't added by
-   * the user of the container, but were added by the container implementation
-   * itself.
+  //TODO: Return a ustring instead when we can break ABI.
+  /** Returns the composite name of a child widget.
+   *
+   * Composite widgets are  children of the container that are considered 
+   * "internal" (implementation details of the container). "Internal" children 
+   * generally weren't added by the user of the container, but were added by 
+   * the container implementation itself.
+   *
+   * The caller is responsible for freeing the returned string.
    *
-   * The user is responsible for freeing the returned string.
+   * @param child The child widget.
+   * @returns The composite name of the child widget.
    */
   _WRAP_VFUNC(char* composite_name(GtkWidget* child), composite_name)
 
-  /** Sets a child property for this container and its child. Child properties
-   * are object properties that are not specific to either the container or the
-   * contained widget, but rather to their relation. Typical examples of child
-   * properties are the position or pack-type of a widget which is contained in
-   * a Gtk::Box.
+  /** Sets a child property for this container and its child.
+   *
+   * Child properties are object properties that are not specific to either the 
+   * container or the contained widget, but rather to their relation. Typical 
+   * examples of child properties are the position or pack-type of a widget 
+   * which is contained in a Gtk::Box.
+   *
+   * @param child The child property.
+   * @param property_id The ID of the child property to set.
+   * @param value The new value for the child property.
+   * @param pspec
    */
   _WRAP_VFUNC(void set_child_property(GtkWidget* child, guint property_id, const GValue* value, GParamSpec* pspec), set_child_property)
 
-  /** Returns a child property for this container and its child. Child
-   * properties are object properties that are not specific to either the
+  /** Returns a child property for this container and its child.
+   *
+   * Child  properties are object properties that are not specific to either the
    * container or the contained widget, but rather to their relation. Typical
    * examples of child properties are the position or pack-type of a widget
    * which is contained in a Gtk::Box.
+   *
+   * @param child The child property.
+   * @param property_id The ID of the child property to get.
+   * @param value A GValue to fill with the child property's value.
+   * @param pspec
    */
   _WRAP_VFUNC(void get_child_property(GtkWidget* child, guint property_id, GValue* value, GParamSpec* pspec) const, get_child_property)