Document private instance data.

Mon Mar 10 11:33:10 2003  Owen Taylor  <otaylor@redhat.com>

        * gobject/tmpl/gtype.sgml gobject/gobject-sections.txt:
        Document private instance data.

docs/reference/ChangeLog

@@ -1,3 +1,8 @@
+Mon Mar 10 11:33:10 2003  Owen Taylor  <otaylor@redhat.com>
+
+	* gobject/tmpl/gtype.sgml gobject/gobject-sections.txt: 
+	Document private instance data.
+
 2003-02-11  Matthias Clasen  <maclas@gmx.de>
 
 	* glib/tmpl/string_utils.sgml: Fix an off-by-one error in the

docs/reference/gobject/gobject-sections.txt

@@ -30,6 +30,7 @@ G_TYPE_FROM_CLASS
 G_TYPE_FROM_INTERFACE
 G_TYPE_INSTANCE_GET_CLASS
 G_TYPE_INSTANCE_GET_INTERFACE
+G_TYPE_INSTANCE_GET_PRIVATE
 G_TYPE_CHECK_INSTANCE
 G_TYPE_CHECK_INSTANCE_CAST
 G_TYPE_CHECK_INSTANCE_TYPE
@@ -52,6 +53,7 @@ g_type_class_ref
 g_type_class_peek
 g_type_class_unref
 g_type_class_peek_parent
+g_type_class_add_private
 g_type_interface_peek
 g_type_interface_peek_parent
 g_type_children
@@ -97,6 +99,7 @@ g_type_check_class_is_a
 g_type_check_is_value_type
 g_type_check_value
 g_type_check_value_holds
+g_type_instance_get_private
 g_type_test_flags
 g_type_name_from_instance
 g_type_name_from_class

docs/reference/gobject/tmpl/enumerations_flags.sgml

@@ -18,12 +18,21 @@ Enumeration and flags types
 
 </para>
 
+@g_type_class: 
+@minimum: 
+@maximum: 
+@n_values: 
+@values: 
 
 <!-- ##### STRUCT GFlagsClass ##### -->
 <para>
 
 </para>
 
+@g_type_class: 
+@mask: 
+@n_values: 
+@values: 
 
 <!-- ##### MACRO G_ENUM_CLASS_TYPE ##### -->
 <para>

docs/reference/gobject/tmpl/gparamspec.sgml

@@ -107,6 +107,13 @@ Retrieve the #GType to intiialize a #GValue for this parameter.
 
 </para>
 
+@g_type_class: 
+@value_type: 
+@finalize: 
+@value_set_default: 
+@value_validate: 
+@values_cmp: 
+@dummy: 
 
 <!-- ##### ENUM GParamFlags ##### -->
 <para>

docs/reference/gobject/tmpl/gtype.sgml

@@ -462,6 +462,17 @@ Returns the interface structure for interface @g_type of a given @instance.
 @c_type: The corresponding C type of @g_type.
 
 
+<!-- ##### MACRO G_TYPE_INSTANCE_GET_PRIVATE ##### -->
+<para>
+Gets the private structure for a particular type.
+The private structure must have been registered in the
+class_init function with g_type_class_add_private().
+</para>
+
+@instance: the instance of a type deriving from @private_type.
+@g_type: the type identifying which private data to retrieve.
+@c_type: The C type for the private structure.
+
 <!-- ##### MACRO G_TYPE_CHECK_INSTANCE ##### -->
 <para>
 
@@ -693,6 +704,48 @@ g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class)));
 @Returns: The parent class of @g_class.
 
 
+<!-- ##### FUNCTION g_type_class_add_private ##### -->
+<para>
+Registers a private structure for a instantiatable type;
+when an object is allocated, the private structures for
+the type and 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
+type's class_init() function. The private structure can
+be retrieved using the G_TYPE_INSTANCE_GET_PRIVATE() macro.
+The following example shows attaching a private structure
+<structname>MyObjectPrivate</structname> to an object
+<structname>MyObject</structname> defined in the standard GObject
+fashion.
+</para>
+<programlisting>
+typedef struct _MyObjectPrivate MyObjectPrivate;
+
+struct _MyObjectPrivate {
+  int some_field;
+};
+
+&num;define MY_OBJECT_GET_PRIVATE(o)  \
+   (G_TYPE_INSTANCE_GET_PRIVATE ((o), MY_TYPE_OBJECT, MyObjectPrivate))
+
+static void
+my_object_class_init (MyObjectClass *klass)
+{
+  g_type_class_add_private (klass, sizeof (MyObjectPrivate));
+}
+
+static int
+my_object_get_some_field (MyObject *my_object)
+{
+  MyObjectPrivate *priv = MY_OBJECT_GET_PRIVATE (my_object);
+
+  return priv->some_field;
+}
+</programlisting>
+
+@g_class: class structure for an instantiatable type
+@private_size: size of private structure.
+
 <!-- ##### FUNCTION g_type_interface_peek ##### -->
 <para>
 Returns the #GTypeInterface structure of an interface to which the passed in 
@@ -751,7 +804,6 @@ Returns the prerequisites of an interfaces type.
 @n_prerequisites: location to return the number of prerequisites, or %NULL
 @Returns: a newly-allocated zero-terminated array of #GType containing 
    the prerequisites of @interface_type
-<!-- # Unused Parameters # -->
 @Since: 2.2
 
 
@@ -1411,5 +1463,9 @@ The fundamental type for #GObject.
 
 </para>
 
-
-
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gobject-docs.sgml" "book" "refsect2" "")
+End:
+-->

docs/reference/gobject/tmpl/gtypemodule.sgml

@@ -68,6 +68,13 @@ in #GTypeModuleClass.
 
 </para>
 
+@parent_class: 
+@load: 
+@unload: 
+@reserved1: 
+@reserved2: 
+@reserved3: 
+@reserved4: 
 
 <!-- ##### FUNCTION g_type_module_use ##### -->
 <para>

docs/reference/gobject/tmpl/gtypeplugin.sgml

@@ -25,6 +25,11 @@ An interface for dynamically loadable types
 
 </para>
 
+@base_iface: 
+@use_plugin: 
+@unuse_plugin: 
+@complete_type_info: 
+@complete_interface_info: 
 
 <!-- ##### USER_FUNCTION GTypePluginUse ##### -->
 <para>

docs/reference/gobject/tmpl/objects.sgml

@@ -27,6 +27,7 @@ to the #GObject implementation and should never be accessed directly.
 
 </para>
 
+@g_type_class: 
 
 <!-- ##### USER_FUNCTION GObjectGetPropertyFunc ##### -->
 <para>

docs/reference/gobject/tmpl/param_value_types.sgml

@@ -840,7 +840,7 @@ See g_param_spec_internal() for details on property names.
 @maximum:       maximum value for the property specified
 @default_value: default value for the property specified
 @flags:         flags for the property specified
-@Returns:  a newly created parameter specification 
+@Returns:  a newly created parameter specification
 
 
 <!-- ##### FUNCTION g_value_set_double ##### -->
@@ -1557,6 +1557,6 @@ See g_param_spec_internal() for details on property names.
 @element_spec:  a #GParamSpec describing the elements contained in 
                 arrays of this property, may be %NULL
 @flags:         flags for the property specified
-@Returns: a newly created parameter specification 
+@Returns: a newly created parameter specification