[glib] gobject: Document that classes/objects/interfaces are zero-filled

[Philip Withnall <pwithnall src gnome org>]

commit 704852ff097f848dcb89ba553431b460938d8d91
Author: Philip Withnall <philip withnall collabora co uk>
Date:   Tue Apr 29 08:47:14 2014 +0100

    gobject: Document that classes/objects/interfaces are zero-filled
    
    On initialisation, GObject guarantees to zero-fill
    class/object/interface structures. Document this so people don’t spend
    forever writing:
        my_object->priv->some_member = NULL;
        my_object->priv->some_other_member = NULL;
    
    https://bugzilla.gnome.org/show_bug.cgi?id=729167

 docs/reference/gobject/tut_howto.xml |    9 ++++++---
 gobject/gtype.c                      |   11 +++++++++--
 gobject/gtype.h                      |    7 +++++++
 3 files changed, 22 insertions(+), 5 deletions(-)
---
diff --git a/docs/reference/gobject/tut_howto.xml b/docs/reference/gobject/tut_howto.xml
index 35b212a..8d1b12c 100644
--- a/docs/reference/gobject/tut_howto.xml
+++ b/docs/reference/gobject/tut_howto.xml
@@ -147,7 +147,9 @@ GType maman_bar_get_type (void);
             macro with the G_DEFINE_TYPE_WITH_CODE() or the G_DEFINE_TYPE_EXTENDED()
             macros. The private structure is then defined in the .c file,
             and can be accessed using the <function>get_instance_private()</function>
-            function generated by the G_DEFINE_TYPE_* macros.
+            function generated by the G_DEFINE_TYPE_* macros. It is automatically
+            zero-filled on creation, so it is unnecessary to explicitly
+            initialize pointer members to NULL.
 <programlisting>
 struct _MamanBarPrivate
 {
@@ -333,7 +335,8 @@ maman_bar_init (MamanBar *self)
 {
   self->priv = maman_bar_get_instance_private (self);
 
-  /* initialize all public and private members to reasonable default values. */
+  /* initialize all public and private members to reasonable default values.
+   * They are all automatically initialized to 0 to begin with. */
 }
 </programlisting>
     </para>
@@ -574,7 +577,7 @@ maman_bar_do_action (MamanBar *self, /* parameters */)
         implementation for this class method in the object's
         <function>class_init</function> function: initialize the
         klass-&gt;do_action field to a pointer to the actual implementation.
-        By default, class method that are not inherited are initialized to
+        By default, class methods that are not inherited are initialized to
         NULL, and thus are to be considered "pure virtual".
 <programlisting>
 static void
diff --git a/gobject/gtype.c b/gobject/gtype.c
index 2909f8a..3db19e6 100644
--- a/gobject/gtype.c
+++ b/gobject/gtype.c
@@ -1780,6 +1780,9 @@ type_iface_blow_holder_info_Wm (TypeNode *iface,
  * directly through g_type_create_instance() which doesn't handle things
  * like singleton objects or object construction.
  *
+ * The extended members of the returned instance are guaranteed to be filled
+ * with zeros.
+ *
  * Note: Do not use this function, unless you're implementing a
  * fundamental type. Also language bindings should not use this
  * function, but g_object_new() instead.
@@ -4409,7 +4412,7 @@ gobject_init_ctor (void)
  * When an object is allocated, the private structures for
  * the type and all of its parent types are allocated
  * sequentially in the same memory block as the public
- * structures.
+ * structures, and are zero-filled.
  *
  * Note that the accumulated size of the private structures of
  * a type and all its parent types cannot exceed 64 KiB.
@@ -4451,6 +4454,8 @@ gobject_init_ctor (void)
  *   my_object->priv = G_TYPE_INSTANCE_GET_PRIVATE (my_object,
  *                                                  MY_TYPE_OBJECT,
  *                                                  MyObjectPrivate);
+ *   /<!-- -->* my_object->priv->some_field will be
+ *    * automatically initialised to 0 *<!-- -->/
  * }
  *
  * static int
@@ -4687,7 +4692,9 @@ g_type_class_get_instance_private_offset (gpointer g_class)
  * when the class is allocated, the private structures for
  * the class and all of its parent types are allocated
  * sequentially in the same memory block as the public
- * structures. This function should be called in the
+ * structures, and are zero-filled.
+ *
+ * This function should be called in the
  * type's get_type() function after the type is registered.
  * The private structure can be retrieved using the
  * G_TYPE_CLASS_GET_PRIVATE() macro.
diff --git a/gobject/gtype.h b/gobject/gtype.h
index 8ceeb96..41dd857 100644
--- a/gobject/gtype.h
+++ b/gobject/gtype.h
@@ -882,10 +882,14 @@ typedef void   (*GClassFinalizeFunc)         (gpointer         g_class,
  * A callback function used by the type system to initialize a new
  * instance of a type. This function initializes all instance members and
  * allocates any resources required by it.
+ *
  * Initialization of a derived instance involves calling all its parent
  * types instance initializers, so the class member of the instance
  * is altered during its initialization to always point to the class that
  * belongs to the type the current initializer was introduced for.
+ *
+ * The extended members of @instance are guaranteed to have been filled with
+ * zeros before this function is called.
  */
 typedef void   (*GInstanceInitFunc)          (GTypeInstance   *instance,
                                              gpointer         g_class);
@@ -897,6 +901,9 @@ typedef void   (*GInstanceInitFunc)          (GTypeInstance   *instance,
  * A callback function used by the type system to initialize a new
  * interface.  This function should initialize all internal data and
  * allocate any resources required by the interface.
+ *
+ * The members of @iface_data are guaranteed to have been filled with
+ * zeros before this function is called.
  */
 typedef void   (*GInterfaceInitFunc)         (gpointer         g_iface,
                                              gpointer         iface_data);