Additions.

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 6ed3361..5140d64 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,8 @@
+2003-03-25  Matthias Clasen  <maclas@gmx.de>
+
+       * gobject/tmpl/param_value_types.sgml: 
+       * gobject/tmpl/objects.sgml: Additions.
+
 2003-03-24  Matthias Clasen  <maclas@gmx.de>
 
        * gobject/tmpl/objects.sgml: Additions.

diff --git a/docs/reference/gobject/gobject-sections.txt b/docs/reference/gobject/gobject-sections.txt
index 3215304..1fa6b91 100644 (file)
--- a/docs/reference/gobject/gobject-sections.txt
+++ b/docs/reference/gobject/gobject-sections.txt
@@ -234,9 +234,9 @@ g_object_set_valist
 g_object_get_valist
 g_object_watch_closure
 g_object_run_dispose
-G_OBJECT_WARN_INVALID_PSPEC
 G_OBJECT_WARN_INVALID_PROPERTY_ID
 <SUBSECTION Private>
+G_OBJECT_WARN_INVALID_PSPEC
 GObjectConstructParam
 </SECTION>
 

diff --git a/docs/reference/gobject/tmpl/objects.sgml b/docs/reference/gobject/tmpl/objects.sgml
index b5a86c8..1a8b4ed 100644 (file)
--- a/docs/reference/gobject/tmpl/objects.sgml
+++ b/docs/reference/gobject/tmpl/objects.sgml
@@ -162,55 +162,64 @@ Installs a new property. This is usually done in the class initializer.
 
 <!-- ##### FUNCTION g_object_class_find_property ##### -->
 <para>
-
+Looks up the #GParamSpec for a property of a class.
 </para>
 
-@oclass: 
-@property_name: 
-@Returns: 
+@oclass: a #GObjectClass
+@property_name: the name of the property to look up
+@Returns: the #GParamSpec for the property, or %NULL if the class doesn't have
+a property of that name
 
 
 <!-- ##### FUNCTION g_object_class_list_properties ##### -->
 <para>
-
+Returns an array of #GParamSpec* for all properties of a class.
 </para>
 
-@oclass: 
-@n_properties: 
-@Returns: 
+@oclass: a #GObjectClass
+@n_properties: return location for the length of the returned array
+@Returns: an array of #GParamSpec* which should be freed after use
 
 
 <!-- ##### FUNCTION g_object_new ##### -->
 <para>
-
+Creates a new instance of a #GObject subtype and sets its properties.
+</para>
+<para>
+Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY) 
+which are not explicitly specified are set to their default values.
 </para>
 
-@object_type: 
-@first_property_name: 
-@Varargs: 
-@Returns: 
-<!-- # Unused Parameters # -->
-@first_param_name: 
+@object_type: the type id of the #GObject subtype to instantiate
+@first_property_name: the name of the first property
+@Varargs: the value of the first property, followed optionally by more
+     name/value pairs, followed by %NULL
+@Returns: a new instance of @object_type
 
 
 <!-- ##### FUNCTION g_object_newv ##### -->
 <para>
-
+Creates a new instance of a #GObject subtype and sets its properties.
+</para>
+<para>
+Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY) 
+which are not explicitly specified are set to their default values.
 </para>
 
-@object_type: 
-@n_parameters: 
-@parameters: 
-@Returns: 
+@object_type: the type id of the #GObject subtype to instantiate
+@n_parameters: the length of the @parameters array
+@parameters: an array of #GParameter
+@Returns: a new instance of @object_type
 
 
 <!-- ##### STRUCT GParameter ##### -->
 <para>
-
+The <structname>GParameter</structname> struct is an auxiliary structure used
+to hand parameter name/value pairs to g_object_newv().
 </para>
 
-@name: 
-@value: 
+@name: the parameter name
+@value: the parameter value
 
 <!-- ##### FUNCTION g_object_ref ##### -->
 <para>
@@ -358,7 +367,7 @@ equivalent to <literal>g_signal_connect_object (..., G_CONNECT_SWAPPED | G_CONNE
 </informalexample>
 
 @object: a #GObject
-@signal_spec: the spec for the first signal 
+@signal_spec: the spec for the first signal
 @Varargs: #GCallback for the first signal, followed by data for the first signal, 
           followed optionally by more signal spec/callback/data triples, 
           followed by %NULL
@@ -376,7 +385,7 @@ means to disconnect any signal with matching callback and data, or
 </para>
 
 @object: a #GObject
-@signal_spec: the spec for the first signal 
+@signal_spec: the spec for the first signal
 @Varargs: #GCallback for the first signal, followed by data for the first signal, 
           followed optionally by more signal spec/callback/data triples, 
           followed by %NULL
@@ -395,8 +404,37 @@ Sets properties on an object.
 
 <!-- ##### FUNCTION g_object_get ##### -->
 <para>
-Gets properties of an object. 
+Gets properties of an object.
+</para>
+<para>
+In general, a copy is made of the property contents and the caller is
+responsible for freeing the memory in the appropriate manner for the type, 
+for instance by calling g_free() or g_object_unref().
 </para>
+<example>
+<title>Using g_object_get(<!-- -->)</title>
+<para>
+An example of using g_object_get() to get the contents
+of three properties - one of type #G_TYPE_INT,
+one of type #G_TYPE_STRING, and one of type #G_TYPE_OBJECT:
+</para>
+<programlisting>
+ gint intval;
+ gchar *strval;
+ GObject *objval; 
+ 
+ g_object_get (my_object,
+               "intproperty", &amp;intval,
+               "strproperty", &amp;strval,
+               "objproperty", &amp;objval,
+               NULL);
+
+ /* Do something with intval, strval, objval */
+ 
+ g_free (strval);
+ g_object_unref (objval);
+</programlisting>
+</example>
 
 @object: a #GObject
 @first_property_name: name of the first property to get
@@ -580,6 +618,14 @@ Sets a property on an object.
 <para>
 Gets a property of an object.
 </para>
+<para>
+In general, a copy is made of the property contents and the caller is
+responsible for freeing the memory in the appropriate manner for the type, 
+for instance by calling g_free() or g_object_unref(). 
+</para>
+<para>
+See g_object_get().
+</para>
 
 @object: a #GObject
 @property_name: the name of the property to get
@@ -588,13 +634,18 @@ Gets a property of an object.
 
 <!-- ##### FUNCTION g_object_new_valist ##### -->
 <para>
-
+Creates a new instance of a #GObject subtype and sets its properties.
+</para>
+<para>
+Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY) 
+which are not explicitly specified are set to their default values.
 </para>
 
-@object_type: 
-@first_property_name: 
-@var_args: 
-@Returns: 
+@object_type: the type id of the #GObject subtype to instantiate
+@first_property_name: the name of the first property
+@var_args: the value of the first property, followed optionally by more
+     name/value pairs, followed by %NULL
+@Returns: a new instance of @object_type
 
 
 <!-- ##### FUNCTION g_object_set_valist ##### -->
@@ -612,6 +663,14 @@ Sets properties on an object.
 <para>
 Gets properties of an object. 
 </para>
+<para>
+In general, a copy is made of the property contents and the caller is
+responsible for freeing the memory in the appropriate manner for the type, 
+for instance by calling g_free() or g_object_unref().
+</para>
+<para>
+See g_object_get().
+</para>
 
 @object: a #GObject
 @first_property_name: name of the first property to get
@@ -638,30 +697,24 @@ as closure data.
 
 <!-- ##### FUNCTION g_object_run_dispose ##### -->
 <para>
-
+Releases all references to other objects. This can be used to break 
+reference cycles.
 </para>
+<note><para>
+This functions should only be called from object system implementations.
+</para></note>
 
-@object: 
-
-
-<!-- ##### MACRO G_OBJECT_WARN_INVALID_PSPEC ##### -->
-<para>
-
-</para>
-
-@object: 
-@pname: 
-@property_id: 
-@pspec: 
+@object: a #GObject
 
 
 <!-- ##### MACRO G_OBJECT_WARN_INVALID_PROPERTY_ID ##### -->
 <para>
-
+This macros should be used to emit a standard warning about unexpected 
+properties in set_property() and get_property() implementations.
 </para>
 
-@object: 
-@property_id: 
-@pspec: 
+@object: the #GObject on which set_property() or get_property() was called
+@property_id: the numeric id of the property
+@pspec: the #GParamSpec of the property
 
 

diff --git a/docs/reference/gobject/tmpl/param_value_types.sgml b/docs/reference/gobject/tmpl/param_value_types.sgml
index 022f48d..3f5da99 100644 (file)
--- a/docs/reference/gobject/tmpl/param_value_types.sgml
+++ b/docs/reference/gobject/tmpl/param_value_types.sgml
@@ -879,10 +879,10 @@ Cast a #GParamSpec instance into a #GParamSpecEnum.
 
 <!-- ##### MACRO G_VALUE_HOLDS_ENUM ##### -->
 <para>
-
+Return whether the given #GValue can hold values derived from type %G_TYPE_ENUM.
 </para>
 
-@value: 
+@value: a valid #GValue structure
 
 
 <!-- ##### MACRO G_TYPE_PARAM_ENUM ##### -->
@@ -951,10 +951,10 @@ Cast a #GParamSpec instance into a #GParamSpecChar.
 
 <!-- ##### MACRO G_VALUE_HOLDS_FLAGS ##### -->
 <para>
-
+Returns whether the given #GValue can hold values derived from type %G_TYPE_FLAGS.
 </para>
 
-@value: 
+@value: a valid #GValue structure
 
 
 <!-- ##### MACRO G_TYPE_PARAM_FLAGS ##### -->
@@ -1023,10 +1023,10 @@ Casts a #GParamSpec instance into a #GParamSpecString.
 
 <!-- ##### MACRO G_VALUE_HOLDS_STRING ##### -->
 <para>
-
+Return whether the given #GValue can hold values of type %G_TYPE_STRING.
 </para>
 
-@value: 
+@value: a valid #GValue structure
 
 
 <!-- ##### MACRO G_TYPE_PARAM_STRING ##### -->
@@ -1131,10 +1131,10 @@ Casts a #GParamSpec instance into a #GParamSpecParam.
 
 <!-- ##### MACRO G_VALUE_HOLDS_PARAM ##### -->
 <para>
-
+Return whether the given #GValue can hold values derived from type %G_TYPE_PARAM.
 </para>
 
-@value: 
+@value: a valid #GValue structure
 
 
 <!-- ##### MACRO G_TYPE_PARAM_PARAM ##### -->
@@ -1230,7 +1230,6 @@ The #GType of #GParamSpecBoxed.
 </para>
 
 
-
 <!-- ##### STRUCT GParamSpecBoxed ##### -->
 <para>
 A #GParamSpec derived structure that contains the meta data for boxed properties.
@@ -1322,10 +1321,11 @@ Casts a #GParamSpec instance into a #GParamSpecPointer.
 
 <!-- ##### MACRO G_VALUE_HOLDS_POINTER ##### -->
 <para>
+Return whether the given #GValue can hold values of type %G_TYPE_POINTER.
 
 </para>
 
-@value: 
+@value: a valid #GValue structure
 
 
 <!-- ##### MACRO G_TYPE_PARAM_POINTER ##### -->
@@ -1390,10 +1390,10 @@ Casts a #GParamSpec instance into a #GParamSpecObject.
 
 <!-- ##### MACRO G_VALUE_HOLDS_OBJECT ##### -->
 <para>
-
+Return whether the given #GValue can hold values derived from type %G_TYPE_OBJECT.
 </para>
 
-@value: 
+@value: a valid #GValue structure
 
 
 <!-- ##### MACRO G_TYPE_PARAM_OBJECT ##### -->