glib r7081 - in trunk: . docs/reference/gobject/tmpl gobject

[stefkost svn gnome org]

Author: stefkost
Date: Sat Jun 21 22:16:14 2008
New Revision: 7081
URL: http://svn.gnome.org/viewvc/glib?rev=7081&view=rev

Log:
	* docs/reference/gobject/tmpl/param_value_types.sgml:
	* gobject/gboxed.c:
	* gobject/gboxed.h:
	* gobject/genums.c:
	* gobject/genums.h:
	* gobject/gobject.c:
	* gobject/gobject.h:
	* gobject/gparam.c:
	* gobject/gparam.h:
	* gobject/gparamspecs.c:
	* gobject/gparamspecs.h:
	* gobject/gvaluetypes.c:
	* gobject/gvaluetypes.h:
	  Migrating docs.



Removed:
   trunk/docs/reference/gobject/tmpl/param_value_types.sgml
Modified:
   trunk/ChangeLog
   trunk/docs/reference/gobject/tmpl/   (props changed)
   trunk/gobject/gboxed.c
   trunk/gobject/gboxed.h
   trunk/gobject/genums.c
   trunk/gobject/genums.h
   trunk/gobject/gobject.c
   trunk/gobject/gobject.h
   trunk/gobject/gparam.c
   trunk/gobject/gparam.h
   trunk/gobject/gparamspecs.c
   trunk/gobject/gparamspecs.h
   trunk/gobject/gvaluetypes.c
   trunk/gobject/gvaluetypes.h

Modified: trunk/gobject/gboxed.c
==============================================================================
--- trunk/gobject/gboxed.c	(original)
+++ trunk/gobject/gboxed.c	Sat Jun 21 22:16:14 2008
@@ -532,6 +532,14 @@
     }
 }
 
+/**
+ * g_value_get_boxed:
+ * @value: a valid #GValue of %G_TYPE_BOXED derived type
+ * 
+ * Get the contents of a %G_TYPE_BOXED derived #GValue.
+ * 
+ * Returns: boxed contents of @value
+ */
 gpointer
 g_value_get_boxed (const GValue *value)
 {
@@ -541,6 +549,16 @@
   return value->data[0].v_pointer;
 }
 
+/**
+ * g_value_dup_boxed:
+ * @value: a valid #GValue of %G_TYPE_BOXED derived type
+ * 
+ * Get the contents of a %G_TYPE_BOXED derived #GValue.
+ * Upon getting, the boxed value is duplicated and needs to be
+ * later freed with g_boxed_free(), e.g. like: g_boxed_free (G_VALUE_TYPE (@value), return_value);
+ * 
+ * Returns: boxed contents of @value
+ */
 gpointer
 g_value_dup_boxed (const GValue *value)
 {
@@ -593,6 +611,13 @@
     }
 }
 
+/**
+ * g_value_set_boxed:
+ * @value: a valid #GValue of %G_TYPE_BOXED derived type
+ * @v_boxed: boxed value to be set
+ * 
+ * Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed.
+ */
 void
 g_value_set_boxed (GValue       *value,
 		   gconstpointer boxed)
@@ -603,6 +628,15 @@
   value_set_boxed_internal (value, boxed, TRUE, TRUE);
 }
 
+/**
+ * g_value_set_static_boxed:
+ * @value: a valid #GValue of %G_TYPE_BOXED derived type
+ * @v_boxed: static boxed value to be set
+ * 
+ * Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed.
+ * The boxed value is assumed to be static, and is thus not duplicated
+ * when setting the #GValue.
+ */
 void
 g_value_set_static_boxed (GValue       *value,
 			  gconstpointer boxed)
@@ -613,6 +647,15 @@
   value_set_boxed_internal (value, boxed, FALSE, FALSE);
 }
 
+/**
+ * g_value_set_boxed_take_ownership:
+ * @value: a valid #GValue of %G_TYPE_BOXED derived type
+ * @v_boxed: duplicated unowned boxed value to be set
+ * 
+ * This is an internal function introduced mainly for C marshallers.
+ * 
+ * Deprecated: 2.4: Use g_value_take_boxed() instead.
+ */
 void
 g_value_set_boxed_take_ownership (GValue       *value,
 				  gconstpointer boxed)
@@ -620,6 +663,17 @@
   g_value_take_boxed (value, boxed);
 }
 
+/**
+ * g_value_take_boxed:
+ * @value: a valid #GValue of %G_TYPE_BOXED derived type
+ * @v_boxed: duplicated unowned boxed value to be set
+ * 
+ * Sets the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed and
+ * takes over the ownership of the callers reference to @v_boxed; 
+ * the caller doesn't have to unref it any more.
+ * 
+ * Since: 2.4
+ */
 void
 g_value_take_boxed (GValue       *value,
 		    gconstpointer boxed)

Modified: trunk/gobject/gboxed.h
==============================================================================
--- trunk/gobject/gboxed.h	(original)
+++ trunk/gobject/gboxed.h	Sat Jun 21 22:16:14 2008
@@ -29,6 +29,14 @@
 
 /* --- type macros --- */
 #define G_TYPE_IS_BOXED(type)	   (G_TYPE_FUNDAMENTAL (type) == G_TYPE_BOXED)
+/**
+ * G_VALUE_HOLDS_BOXED:
+ * @value: a valid #GValue structure
+ * 
+ * Checks whether the given #GValue can hold values derived from type %G_TYPE_BOXED.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_VALUE_HOLDS_BOXED(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_BOXED))
 
 

Modified: trunk/gobject/genums.c
==============================================================================
--- trunk/gobject/genums.c	(original)
+++ trunk/gobject/genums.c	Sat Jun 21 22:16:14 2008
@@ -546,6 +546,13 @@
   return NULL;
 }
 
+/**
+ * g_value_set_enum:
+ * @value: a valid #GValue whose type is derived from %G_TYPE_ENUM
+ * @v_enum: enum value to be set
+ * 
+ * Set the contents of a %G_TYPE_ENUM #GValue to @v_enum.
+ */
 void
 g_value_set_enum (GValue *value,
 		  gint    v_enum)
@@ -555,6 +562,14 @@
   value->data[0].v_long = v_enum;
 }
 
+/**
+ * g_value_get_enum:
+ * @value: a valid #GValue whose type is derived from %G_TYPE_ENUM
+ * 
+ * Get the contents of a %G_TYPE_ENUM #GValue.
+ * 
+ * Returns: enum contents of @value
+ */
 gint
 g_value_get_enum (const GValue *value)
 {
@@ -563,6 +578,13 @@
   return value->data[0].v_long;
 }
 
+/**
+ * g_value_set_flags:
+ * @value: a valid #GValue whose type is derived from %G_TYPE_FLAGS
+ * @v_flags: flags value to be set
+ * 
+ * Set the contents of a %G_TYPE_FLAGS #GValue to @v_flags.
+ */
 void
 g_value_set_flags (GValue *value,
 		   guint   v_flags)
@@ -572,6 +594,14 @@
   value->data[0].v_ulong = v_flags;
 }
 
+/**
+ * g_value_get_flags:
+ * @value: a valid #GValue whose type is derived from %G_TYPE_FLAGS
+ * 
+ * Get the contents of a %G_TYPE_FLAGS #GValue.
+ * 
+ * Returns: flags contents of @value
+ */
 guint
 g_value_get_flags (const GValue *value)
 {

Modified: trunk/gobject/genums.h
==============================================================================
--- trunk/gobject/genums.h	(original)
+++ trunk/gobject/genums.h	Sat Jun 21 22:16:14 2008
@@ -116,7 +116,23 @@
 #define G_FLAGS_CLASS_TYPE_NAME(class) (g_type_name (G_FLAGS_CLASS_TYPE (class)))
 
 
+/**
+ * G_VALUE_HOLDS_ENUM:
+ * @value: a valid #GValue structure
+ * 
+ * Checks whether the given #GValue can hold values derived from type %G_TYPE_ENUM.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_VALUE_HOLDS_ENUM(value)      (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_ENUM))
+/**
+ * G_VALUE_HOLDS_FLAGS:
+ * @value: a valid #GValue structure
+ * 
+ * Checks whether the given #GValue can hold values derived from type %G_TYPE_FLAGS.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_VALUE_HOLDS_FLAGS(value)     (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_FLAGS))
 
 

Modified: trunk/gobject/gobject.c
==============================================================================
--- trunk/gobject/gobject.c	(original)
+++ trunk/gobject/gobject.c	Sat Jun 21 22:16:14 2008
@@ -2718,6 +2718,24 @@
   return NULL;
 }
 
+/**
+ * g_value_set_object:
+ * @value: a valid #GValue of %G_TYPE_OBJECT derived type
+ * @v_object: object value to be set
+ * 
+ * Set the contents of a %G_TYPE_OBJECT derived #GValue to @v_object.
+ * 
+ * g_value_set_object() increases the reference count of @v_object
+ * (the #GValue holds a reference to @v_object).
+ * If you do not wish to increase the reference count of the object
+ * (i.e. you wish to pass your current reference to the #GValue because you no
+ * longer need it),
+ * use g_value_take_object() instead.
+ * 
+ * It is important that your #GValue holds a reference to @v_object (either its
+ * own, or one it has taken) to ensure that the object won't be destroyed while
+ * the #GValue still exists).
+ */
 void
 g_value_set_object (GValue   *value,
 		    gpointer  v_object)
@@ -2743,6 +2761,15 @@
     g_object_unref (old);
 }
 
+/**
+ * g_value_set_object_take_ownership:
+ * @value: a valid #GValue of %G_TYPE_OBJECT derived type
+ * @v_object: object value to be set
+ * 
+ * This is an internal function introduced mainly for C marshallers.
+ * 
+ * Deprecated: 2.4: Use g_value_take_object() instead.
+ */
 void
 g_value_set_object_take_ownership (GValue  *value,
 				   gpointer v_object)
@@ -2750,6 +2777,21 @@
   g_value_take_object (value, v_object);
 }
 
+/**
+ * g_value_take_object:
+ * @value: a valid #GValue of %G_TYPE_OBJECT derived type
+ * @v_object: object value to be set
+ * 
+ * Sets the contents of a %G_TYPE_OBJECT derived #GValue to @v_object 
+ * and takes over the ownership of the callers reference to @v_object; 
+ * the caller doesn't have to unref it any more (i.e. the reference
+ * count of the object is not increased).
+ * 
+ * If you want the #GValue to hold its own reference to @v_object, use
+ * g_value_set_object() instead.
+ * 
+ * Since: 2.4
+ */
 void
 g_value_take_object (GValue  *value,
 		     gpointer v_object)
@@ -2771,6 +2813,14 @@
     }
 }
 
+/**
+ * g_value_get_object:
+ * @value: a valid #GValue of %G_TYPE_OBJECT derived type
+ * 
+ * Get the contents of a %G_TYPE_OBJECT derived #GValue.
+ * 
+ * Returns: object contents of @value
+ */
 gpointer
 g_value_get_object (const GValue *value)
 {
@@ -2779,6 +2829,14 @@
   return value->data[0].v_pointer;
 }
 
+/**
+ * g_value_dup_object:
+ * @value: a valid #GValue whose type is derived from %G_TYPE_OBJECT
+ * 
+ * Get the contents of a %G_TYPE_OBJECT derived #GValue, increasing its reference count.
+ * 
+ * Returns: object content of @value, should be unreferenced when no longer needed.
+ */
 gpointer
 g_value_dup_object (const GValue *value)
 {

Modified: trunk/gobject/gobject.h
==============================================================================
--- trunk/gobject/gobject.h	(original)
+++ trunk/gobject/gobject.h	Sat Jun 21 22:16:14 2008
@@ -119,6 +119,14 @@
  *  should not be freed.
  */
 #define G_OBJECT_CLASS_NAME(class)  (g_type_name (G_OBJECT_CLASS_TYPE (class)))
+/**
+ * G_VALUE_HOLDS_OBJECT:
+ * @value: a valid #GValue structure
+ * 
+ * Checks whether the given #GValue can hold values derived from type %G_TYPE_OBJECT.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_VALUE_HOLDS_OBJECT(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_OBJECT))
 
 /* --- type macros --- */

Modified: trunk/gobject/gparam.c
==============================================================================
--- trunk/gobject/gparam.c	(original)
+++ trunk/gobject/gparam.c	Sat Jun 21 22:16:14 2008
@@ -1386,6 +1386,13 @@
   return g_type_register_static (G_TYPE_PARAM, name, &info, 0);
 }
 
+/**
+ * g_value_set_param:
+ * @value: a valid #GValue of type %G_TYPE_PARAM
+ * @param: the #GParamSpec to be set
+ * 
+ * Set the contents of a %G_TYPE_PARAM #GValue to @param.
+ */
 void
 g_value_set_param (GValue     *value,
 		   GParamSpec *param)
@@ -1401,6 +1408,15 @@
     g_param_spec_ref (value->data[0].v_pointer);
 }
 
+/**
+ * g_value_set_param_take_ownership:
+ * @value: a valid #GValue of type %G_TYPE_PARAM
+ * @param: the #GParamSpec to be set
+ * 
+ * This is an internal function introduced mainly for C marshallers.
+ * 
+ * Deprecated: 2.4: Use g_value_take_param() instead.
+ */
 void
 g_value_set_param_take_ownership (GValue     *value,
 				  GParamSpec *param)
@@ -1408,6 +1424,17 @@
   g_value_take_param (value, param);
 }
 
+/**
+ * g_value_take_param:
+ * @value: a valid #GValue of type %G_TYPE_PARAM
+ * @param: the #GParamSpec to be set
+ * 
+ * Sets the contents of a %G_TYPE_PARAM #GValue to @param and
+ * takes over the ownership of the callers reference to @param; 
+ * the caller doesn't have to unref it any more.
+ * 
+ * Since: 2.4
+ */
 void
 g_value_take_param (GValue     *value,
 		    GParamSpec *param)
@@ -1421,6 +1448,14 @@
   value->data[0].v_pointer = param; /* we take over the reference count */
 }
 
+/**
+ * g_value_get_param:
+ * @value: a valid #GValue whose type is derived from %G_TYPE_PARAM
+ * 
+ * Get the contents of a %G_TYPE_PARAM #GValue.
+ * 
+ * Returns: #GParamSpec content of @value
+ */
 GParamSpec*
 g_value_get_param (const GValue *value)
 {
@@ -1429,6 +1464,14 @@
   return value->data[0].v_pointer;
 }
 
+/**
+ * g_value_dup_param:
+ * @value: a valid #GValue whose type is derived from %G_TYPE_PARAM
+ * 
+ * Get the contents of a %G_TYPE_PARAM #GValue, increasing its reference count.
+ * 
+ * Returns: #GParamSpec content of @value, should be unreferenced when no longer needed.
+ */
 GParamSpec*
 g_value_dup_param (const GValue *value)
 {

Modified: trunk/gobject/gparam.h
==============================================================================
--- trunk/gobject/gparam.h	(original)
+++ trunk/gobject/gparam.h	Sat Jun 21 22:16:14 2008
@@ -99,6 +99,14 @@
  * Retrieves the #GType to initialize a #GValue for this parameter.
  */
 #define	G_PARAM_SPEC_VALUE_TYPE(pspec)	(G_PARAM_SPEC (pspec)->value_type)
+/**
+ * G_VALUE_HOLDS_PARAM:
+ * @value: a valid #GValue structure
+ * 
+ * Checks whether the given #GValue can hold values derived from type %G_TYPE_PARAM.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_VALUE_HOLDS_PARAM(value)	(G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_PARAM))
        
 

Modified: trunk/gobject/gparamspecs.c
==============================================================================
--- trunk/gobject/gparamspecs.c	(original)
+++ trunk/gobject/gparamspecs.c	Sat Jun 21 22:16:14 2008
@@ -16,7 +16,23 @@
  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  * Boston, MA 02111-1307, USA.
  */
-
+/**
+ * SECTION:param_value_types
+ * @Short_description: Standard Parameter and Value Types
+ * @See_also:#GParamSpec, #GValue, g_object_class_install_property().
+ * @Title: Parameters and Values
+ * 
+ * #GValue provides an abstract container structure which can be copied,
+ * transformed and compared while holding a value of any (derived) type, which
+ * is registered as a #GType with a #GTypeValueTable in its #GTypeInfo structure.
+ * Parameter specifications for most value types can be created as
+ * #GParamSpec derived instances, to implement e.g. #GObject properties which
+ * operate on #GValue containers.
+ * 
+ * Parameter names need to start with a letter (a-z or A-Z). Subsequent
+ * characters can be letters, numbers or a '-'.
+ * All other characters are replaced by a '-' during construction.
+ */
 /*
  * MT safe
  */
@@ -1493,6 +1509,20 @@
 
 /* --- GParamSpec initialization --- */
 
+/**
+ * g_param_spec_char:
+ * @name: canonical name of the property specified
+ * @nick: nick name for the property specified
+ * @blurb: description of the property specified
+ * @minimum: minimum value for the property specified
+ * @maximum: maximum value for the property specified
+ * @default_value: default value for the property specified
+ * @flags: flags for the property specified
+ * 
+ * Creates a new #GParamSpecChar instance specifying a %G_TYPE_CHAR property.
+ * 
+ * Returns: a newly created parameter specification
+ */
 GParamSpec*
 g_param_spec_char (const gchar *name,
 		   const gchar *nick,
@@ -1519,6 +1549,20 @@
   return G_PARAM_SPEC (cspec);
 }
 
+/**
+ * g_param_spec_uchar:
+ * @name: canonical name of the property specified
+ * @nick: nick name for the property specified
+ * @blurb: description of the property specified
+ * @minimum: minimum value for the property specified
+ * @maximum: maximum value for the property specified
+ * @default_value: default value for the property specified
+ * @flags: flags for the property specified
+ * 
+ * Creates a new #GParamSpecUChar instance specifying a %G_TYPE_UCHAR property.
+ * 
+ * Returns: a newly created parameter specification
+ */
 GParamSpec*
 g_param_spec_uchar (const gchar *name,
 		    const gchar *nick,
@@ -1545,6 +1589,21 @@
   return G_PARAM_SPEC (uspec);
 }
 
+/**
+ * g_param_spec_boolean:
+ * @name: canonical name of the property specified
+ * @nick: nick name for the property specified
+ * @blurb: description of the property specified
+ * @default_value: default value for the property specified
+ * @flags: flags for the property specified
+ * 
+ * Creates a new #GParamSpecBoolean instance specifying a %G_TYPE_BOOLEAN 
+ * property.
+ * 
+ * See g_param_spec_internal() for details on property names.
+ * 
+ * Returns: a newly created parameter specification
+ */
 GParamSpec*
 g_param_spec_boolean (const gchar *name,
 		      const gchar *nick,
@@ -1567,6 +1626,22 @@
   return G_PARAM_SPEC (bspec);
 }
 
+/**
+ * g_param_spec_int:
+ * @name: canonical name of the property specified
+ * @nick: nick name for the property specified
+ * @blurb: description of the property specified
+ * @minimum: minimum value for the property specified
+ * @maximum: maximum value for the property specified
+ * @default_value: default value for the property specified
+ * @flags: flags for the property specified
+ * 
+ * Creates a new #GParamSpecInt instance specifying a %G_TYPE_INT property.
+ * 
+ * See g_param_spec_internal() for details on property names.
+ * 
+ * Returns: a newly created parameter specification
+ */
 GParamSpec*
 g_param_spec_int (const gchar *name,
 		  const gchar *nick,
@@ -1593,6 +1668,22 @@
   return G_PARAM_SPEC (ispec);
 }
 
+/**
+ * g_param_spec_uint:
+ * @name: canonical name of the property specified
+ * @nick: nick name for the property specified
+ * @blurb: description of the property specified
+ * @minimum: minimum value for the property specified
+ * @maximum: maximum value for the property specified
+ * @default_value: default value for the property specified
+ * @flags: flags for the property specified
+ * 
+ * Creates a new #GParamSpecUInt instance specifying a %G_TYPE_UINT property.
+ * 
+ * See g_param_spec_internal() for details on property names.
+ * 
+ * Returns: a newly created parameter specification
+ */
 GParamSpec*
 g_param_spec_uint (const gchar *name,
 		   const gchar *nick,
@@ -1619,6 +1710,22 @@
   return G_PARAM_SPEC (uspec);
 }
 
+/**
+ * g_param_spec_long:
+ * @name: canonical name of the property specified
+ * @nick: nick name for the property specified
+ * @blurb: description of the property specified
+ * @minimum: minimum value for the property specified
+ * @maximum: maximum value for the property specified
+ * @default_value: default value for the property specified
+ * @flags: flags for the property specified
+ * 
+ * Creates a new #GParamSpecLong instance specifying a %G_TYPE_LONG property.
+ * 
+ * See g_param_spec_internal() for details on property names.
+ * 
+ * Returns: a newly created parameter specification
+ */
 GParamSpec*
 g_param_spec_long (const gchar *name,
 		   const gchar *nick,
@@ -1645,6 +1752,22 @@
   return G_PARAM_SPEC (lspec);
 }
 
+/**
+ * g_param_spec_ulong:
+ * @name: canonical name of the property specified
+ * @nick: nick name for the property specified
+ * @blurb: description of the property specified
+ * @minimum: minimum value for the property specified
+ * @maximum: maximum value for the property specified
+ * @default_value: default value for the property specified
+ * @flags: flags for the property specified
+ * 
+ * Creates a new #GParamSpecULong instance specifying a %G_TYPE_ULONG property.
+ * 
+ * See g_param_spec_internal() for details on property names.
+ * 
+ * Returns: a newly created parameter specification
+ */
 GParamSpec*
 g_param_spec_ulong (const gchar *name,
 		    const gchar *nick,
@@ -1671,6 +1794,22 @@
   return G_PARAM_SPEC (uspec);
 }
 
+/**
+ * g_param_spec_int64:
+ * @name: canonical name of the property specified
+ * @nick: nick name for the property specified
+ * @blurb: description of the property specified
+ * @minimum: minimum value for the property specified
+ * @maximum: maximum value for the property specified
+ * @default_value: default value for the property specified
+ * @flags: flags for the property specified
+ * 
+ * Creates a new #GParamSpecInt64 instance specifying a %G_TYPE_INT64 property.
+ * 
+ * See g_param_spec_internal() for details on property names.
+ * 
+ * Returns: a newly created parameter specification
+ */
 GParamSpec*
 g_param_spec_int64 (const gchar *name,
 		    const gchar *nick,
@@ -1697,6 +1836,23 @@
   return G_PARAM_SPEC (lspec);
 }
 
+/**
+ * g_param_spec_uint64:
+ * @name: canonical name of the property specified
+ * @nick: nick name for the property specified
+ * @blurb: description of the property specified
+ * @minimum: minimum value for the property specified
+ * @maximum: maximum value for the property specified
+ * @default_value: default value for the property specified
+ * @flags: flags for the property specified
+ * 
+ * Creates a new #GParamSpecUInt64 instance specifying a %G_TYPE_UINT64 
+ * property.
+ * 
+ * See g_param_spec_internal() for details on property names.
+ * 
+ * Returns: a newly created parameter specification
+ */
 GParamSpec*
 g_param_spec_uint64 (const gchar *name,
 		     const gchar *nick,
@@ -1723,6 +1879,22 @@
   return G_PARAM_SPEC (uspec);
 }
 
+/**
+ * g_param_spec_unichar:
+ * @name: canonical name of the property specified
+ * @nick: nick name for the property specified
+ * @blurb: description of the property specified
+ * @default_value: default value for the property specified
+ * @flags: flags for the property specified
+ * 
+ * Creates a new #GParamSpecUnichar instance specifying a %G_TYPE_UINT 
+ * property. #GValue structures for this property can be accessed with 
+ * g_value_set_uint() and g_value_get_uint().
+ * 
+ * See g_param_spec_internal() for details on property names.
+ * 
+ * Returns: a newly created parameter specification
+ */
 GParamSpec*
 g_param_spec_unichar (const gchar *name,
 		      const gchar *nick,
@@ -1743,6 +1915,22 @@
   return G_PARAM_SPEC (uspec);
 }
 
+/**
+ * g_param_spec_enum:
+ * @name: canonical name of the property specified
+ * @nick: nick name for the property specified
+ * @blurb: description of the property specified
+ * @enum_type: a #GType derived from %G_TYPE_ENUM
+ * @default_value: default value for the property specified
+ * @flags: flags for the property specified
+ * 
+ * Creates a new #GParamSpecEnum instance specifying a %G_TYPE_ENUM
+ * property.
+ * 
+ * See g_param_spec_internal() for details on property names.
+ * 
+ * Returns: a newly created parameter specification
+ */
 GParamSpec*
 g_param_spec_enum (const gchar *name,
 		   const gchar *nick,
@@ -1773,6 +1961,22 @@
   return G_PARAM_SPEC (espec);
 }
 
+/**
+ * g_param_spec_flags:
+ * @name: canonical name of the property specified
+ * @nick: nick name for the property specified
+ * @blurb: description of the property specified
+ * @flags_type: a #GType derived from %G_TYPE_FLAGS
+ * @default_value: default value for the property specified
+ * @flags: flags for the property specified
+ * 
+ * Creates a new #GParamSpecFlags instance specifying a %G_TYPE_FLAGS
+ * property.
+ * 
+ * See g_param_spec_internal() for details on property names.
+ * 
+ * Returns: a newly created parameter specification
+ */
 GParamSpec*
 g_param_spec_flags (const gchar *name,
 		    const gchar *nick,
@@ -1803,6 +2007,22 @@
   return G_PARAM_SPEC (fspec);
 }
 
+/**
+ * g_param_spec_float:
+ * @name: canonical name of the property specified
+ * @nick: nick name for the property specified
+ * @blurb: description of the property specified
+ * @minimum: minimum value for the property specified
+ * @maximum: maximum value for the property specified
+ * @default_value: default value for the property specified
+ * @flags: flags for the property specified
+ * 
+ * Creates a new #GParamSpecFloat instance specifying a %G_TYPE_FLOAT property.
+ * 
+ * See g_param_spec_internal() for details on property names.
+ * 
+ * Returns: a newly created parameter specification
+ */
 GParamSpec*
 g_param_spec_float (const gchar *name,
 		    const gchar *nick,
@@ -1829,6 +2049,23 @@
   return G_PARAM_SPEC (fspec);
 }
 
+/**
+ * g_param_spec_double:
+ * @name: canonical name of the property specified
+ * @nick: nick name for the property specified
+ * @blurb: description of the property specified
+ * @minimum: minimum value for the property specified
+ * @maximum: maximum value for the property specified
+ * @default_value: default value for the property specified
+ * @flags: flags for the property specified
+ * 
+ * Creates a new #GParamSpecDouble instance specifying a %G_TYPE_DOUBLE 
+ * property.
+ * 
+ * See g_param_spec_internal() for details on property names.
+ * 
+ * Returns: a newly created parameter specification
+ */
 GParamSpec*
 g_param_spec_double (const gchar *name,
 		     const gchar *nick,
@@ -1855,6 +2092,20 @@
   return G_PARAM_SPEC (dspec);
 }
 
+/**
+ * g_param_spec_string:
+ * @name: canonical name of the property specified
+ * @nick: nick name for the property specified
+ * @blurb: description of the property specified
+ * @default_value: default value for the property specified
+ * @flags: flags for the property specified
+ * 
+ * Creates a new #GParamSpecString instance.
+ * 
+ * See g_param_spec_internal() for details on property names.
+ * 
+ * Returns: a newly created parameter specification
+ */
 GParamSpec*
 g_param_spec_string (const gchar *name,
 		     const gchar *nick,
@@ -1873,6 +2124,21 @@
   return G_PARAM_SPEC (sspec);
 }
 
+/**
+ * g_param_spec_param:
+ * @name: canonical name of the property specified
+ * @nick: nick name for the property specified
+ * @blurb: description of the property specified
+ * @param_type: a #GType derived from %G_TYPE_PARAM
+ * @flags: flags for the property specified
+ * 
+ * Creates a new #GParamSpecParam instance specifying a %G_TYPE_PARAM
+ * property.
+ * 
+ * See g_param_spec_internal() for details on property names.
+ * 
+ * Returns: a newly created parameter specification
+ */
 GParamSpec*
 g_param_spec_param (const gchar *name,
 		    const gchar *nick,
@@ -1894,6 +2160,21 @@
   return G_PARAM_SPEC (pspec);
 }
 
+/**
+ * g_param_spec_boxed:
+ * @name: canonical name of the property specified
+ * @nick: nick name for the property specified
+ * @blurb: description of the property specified
+ * @boxed_type: %G_TYPE_BOXED derived type of this property
+ * @flags: flags for the property specified
+ * 
+ * Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_BOXED 
+ * derived property.
+ * 
+ * See g_param_spec_internal() for details on property names.
+ * 
+ * Returns: a newly created parameter specification
+ */
 GParamSpec*
 g_param_spec_boxed (const gchar *name,
 		    const gchar *nick,
@@ -1916,6 +2197,19 @@
   return G_PARAM_SPEC (bspec);
 }
 
+/**
+ * g_param_spec_pointer:
+ * @name: canonical name of the property specified
+ * @nick: nick name for the property specified
+ * @blurb: description of the property specified
+ * @flags: flags for the property specified
+ * 
+ * Creates a new #GParamSpecPoiner instance specifying a pointer property.
+ * 
+ * See g_param_spec_internal() for details on property names.
+ * 
+ * Returns: a newly created parameter specification
+ */
 GParamSpec*
 g_param_spec_pointer (const gchar *name,
 		      const gchar *nick,
@@ -1932,6 +2226,23 @@
   return G_PARAM_SPEC (pspec);
 }
 
+/**
+ * g_param_spec_gtype:
+ * @name: canonical name of the property specified
+ * @nick: nick name for the property specified
+ * @blurb: description of the property specified
+ * @is_a_type: a #GType whose subtypes are allowed as values
+ *  of the property (use %G_TYPE_NONE for any type)
+ * @flags: flags for the property specified
+ * 
+ * Creates a new #GParamSpecGType instance specifying a 
+ * %G_TYPE_GTYPE property. 
+ * 
+ * See g_param_spec_internal() for details on property names.
+ * 
+ * Since: 2.10
+ * Returns: a newly created parameter specification
+ */
 GParamSpec*
 g_param_spec_gtype (const gchar *name,
 		    const gchar *nick,
@@ -1952,6 +2263,24 @@
   return G_PARAM_SPEC (tspec);
 }
 
+/**
+ * g_param_spec_value_array:
+ * @name: canonical name of the property specified
+ * @nick: nick name for the property specified
+ * @blurb: description of the property specified
+ * @element_spec: a #GParamSpec describing the elements contained in 
+ *  arrays of this property, may be %NULL
+ * @flags: flags for the property specified
+ * 
+ * Creates a new #GParamSpecValueArray instance specifying a 
+ * %G_TYPE_VALUE_ARRAY property. %G_TYPE_VALUE_ARRAY is a %G_TYPE_BOXED 
+ * type, as such, #GValue structures for this property can be accessed 
+ * with g_value_set_boxed() and g_value_get_boxed().
+ * 
+ * See g_param_spec_internal() for details on property names.
+ * 
+ * Returns: a newly created parameter specification
+ */
 GParamSpec*
 g_param_spec_value_array (const gchar *name,
 			  const gchar *nick,
@@ -1978,6 +2307,21 @@
   return G_PARAM_SPEC (aspec);
 }
 
+/**
+ * g_param_spec_object:
+ * @name: canonical name of the property specified
+ * @nick: nick name for the property specified
+ * @blurb: description of the property specified
+ * @object_type: %G_TYPE_OBJECT derived type of this property
+ * @flags: flags for the property specified
+ * 
+ * Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_OBJECT 
+ * derived property.
+ * 
+ * See g_param_spec_internal() for details on property names.
+ * 
+ * Returns: a newly created parameter specification
+ */
 GParamSpec*
 g_param_spec_object (const gchar *name,
 		     const gchar *nick,
@@ -1999,6 +2343,18 @@
   return G_PARAM_SPEC (ospec);
 }
 
+/**
+ * g_param_spec_override:
+ * @name: the name of the property.
+ * @overridden: The property that is being overridden
+ * 
+ * Creates a new property of type #GParamSpecOverride. This is used
+ * to direct operations to another paramspec, and will not be directly
+ * useful unless you are implementing a new base type similar to GObject.
+ * 
+ * Since: 2.4
+ * Returns: the newly created #GParamSpec
+ */
 GParamSpec*
 g_param_spec_override (const gchar *name,
 		       GParamSpec  *overridden)

Modified: trunk/gobject/gparamspecs.h
==============================================================================
--- trunk/gobject/gparamspecs.h	(original)
+++ trunk/gobject/gparamspecs.h	Sat Jun 21 22:16:14 2008
@@ -33,71 +33,520 @@
 G_BEGIN_DECLS
 
 /* --- type macros --- */
+/**
+ * G_TYPE_PARAM_CHAR:
+ * 
+ * The #GType of #GParamSpecChar.
+ */
 #define	G_TYPE_PARAM_CHAR		   (g_param_spec_types[0])
+/**
+ * G_IS_PARAM_SPEC_CHAR:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_CHAR.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_IS_PARAM_SPEC_CHAR(pspec)        (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_CHAR))
+/**
+ * G_PARAM_SPEC_CHAR:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Cast a #GParamSpec instance into a #GParamSpecChar.
+ */
 #define G_PARAM_SPEC_CHAR(pspec)           (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_CHAR, GParamSpecChar))
+
+/**
+ * G_TYPE_PARAM_UCHAR:
+ * 
+ * The #GType of #GParamSpecUChar.
+ */
 #define	G_TYPE_PARAM_UCHAR		   (g_param_spec_types[1])
+/**
+ * G_IS_PARAM_SPEC_UCHAR:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UCHAR.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_IS_PARAM_SPEC_UCHAR(pspec)       (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_UCHAR))
+/**
+ * G_PARAM_SPEC_UCHAR:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Cast a #GParamSpec instance into a #GParamSpecUChar.
+ */
 #define G_PARAM_SPEC_UCHAR(pspec)          (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_UCHAR, GParamSpecUChar))
+
+/**
+ * G_TYPE_PARAM_BOOLEAN:
+ * 
+ * The #GType of #GParamSpecBoolean.
+ */
 #define	G_TYPE_PARAM_BOOLEAN		   (g_param_spec_types[2])
+/**
+ * G_IS_PARAM_SPEC_BOOLEAN:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_BOOLEAN.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_IS_PARAM_SPEC_BOOLEAN(pspec)     (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_BOOLEAN))
+/**
+ * G_PARAM_SPEC_BOOLEAN:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Cast a #GParamSpec instance into a #GParamSpecBoolean.
+ */
 #define G_PARAM_SPEC_BOOLEAN(pspec)        (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_BOOLEAN, GParamSpecBoolean))
+
+/**
+ * G_TYPE_PARAM_INT:
+ * 
+ * The #GType of #GParamSpecInt.
+ */
 #define	G_TYPE_PARAM_INT		   (g_param_spec_types[3])
+/**
+ * G_IS_PARAM_SPEC_INT:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_INT.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_IS_PARAM_SPEC_INT(pspec)         (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_INT))
+/**
+ * G_PARAM_SPEC_INT:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Cast a #GParamSpec instance into a #GParamSpecInt.
+ */
 #define G_PARAM_SPEC_INT(pspec)            (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_INT, GParamSpecInt))
+
+/**
+ * G_TYPE_PARAM_UINT:
+ * 
+ * The #GType of #GParamSpecUInt.
+ */
 #define	G_TYPE_PARAM_UINT		   (g_param_spec_types[4])
+/**
+ * G_IS_PARAM_SPEC_UINT:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_IS_PARAM_SPEC_UINT(pspec)        (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_UINT))
+/**
+ * G_PARAM_SPEC_UINT:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Cast a #GParamSpec instance into a #GParamSpecUInt.
+ */
 #define G_PARAM_SPEC_UINT(pspec)           (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_UINT, GParamSpecUInt))
+
+/**
+ * G_TYPE_PARAM_LONG:
+ * 
+ * The #GType of #GParamSpecLong.
+ */
 #define	G_TYPE_PARAM_LONG		   (g_param_spec_types[5])
+/**
+ * G_IS_PARAM_SPEC_LONG:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_LONG.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_IS_PARAM_SPEC_LONG(pspec)        (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_LONG))
+/**
+ * G_PARAM_SPEC_LONG:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Cast a #GParamSpec instance into a #GParamSpecLong.
+ */
 #define G_PARAM_SPEC_LONG(pspec)           (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_LONG, GParamSpecLong))
+
+/**
+ * G_TYPE_PARAM_ULONG:
+ * 
+ * The #GType of #GParamSpecULong.
+ */
 #define	G_TYPE_PARAM_ULONG		   (g_param_spec_types[6])
+/**
+ * G_IS_PARAM_SPEC_ULONG:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_ULONG.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_IS_PARAM_SPEC_ULONG(pspec)       (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_ULONG))
+/**
+ * G_PARAM_SPEC_ULONG:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Cast a #GParamSpec instance into a #GParamSpecULong.
+ */
 #define G_PARAM_SPEC_ULONG(pspec)          (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_ULONG, GParamSpecULong))
+
+/**
+ * G_TYPE_PARAM_INT64:
+ * 
+ * The #GType of #GParamSpecInt64.
+ */
 #define	G_TYPE_PARAM_INT64		   (g_param_spec_types[7])
+/**
+ * G_IS_PARAM_SPEC_INT64:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_INT64.
+ *
+ * Returns: %TRUE on success.
+ */
 #define G_IS_PARAM_SPEC_INT64(pspec)       (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_INT64))
+/**
+ * G_PARAM_SPEC_INT64:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Cast a #GParamSpec instance into a #GParamSpecInt64.
+ */
 #define G_PARAM_SPEC_INT64(pspec)          (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_INT64, GParamSpecInt64))
+
+/**
+ * G_TYPE_PARAM_UINT64:
+ * 
+ * The #GType of #GParamSpecUInt64.
+ */
 #define	G_TYPE_PARAM_UINT64		   (g_param_spec_types[8])
+/**
+ * G_IS_PARAM_SPEC_UINT64:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT64.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_IS_PARAM_SPEC_UINT64(pspec)      (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_UINT64))
+/**
+ * G_PARAM_SPEC_UINT64:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Cast a #GParamSpec instance into a #GParamSpecUInt64.
+ */
 #define G_PARAM_SPEC_UINT64(pspec)         (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_UINT64, GParamSpecUInt64))
+
+/**
+ * G_TYPE_PARAM_UNICHAR:
+ * 
+ * The #GType of #GParamSpecUnichar.
+ */
 #define	G_TYPE_PARAM_UNICHAR		   (g_param_spec_types[9])
+/**
+ * G_PARAM_SPEC_UNICHAR:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Cast a #GParamSpec instance into a #GParamSpecUnichar.
+ */
 #define G_PARAM_SPEC_UNICHAR(pspec)        (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_UNICHAR, GParamSpecUnichar))
+/**
+ * G_IS_PARAM_SPEC_UNICHAR:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UNICHAR.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_IS_PARAM_SPEC_UNICHAR(pspec)     (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_UNICHAR))
+
+/**
+ * G_TYPE_PARAM_ENUM:
+ * 
+ * The #GType of #GParamSpecEnum.
+ */
 #define	G_TYPE_PARAM_ENUM		   (g_param_spec_types[10])
+/**
+ * G_IS_PARAM_SPEC_ENUM:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_ENUM.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_IS_PARAM_SPEC_ENUM(pspec)        (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_ENUM))
+/**
+ * G_PARAM_SPEC_ENUM:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Cast a #GParamSpec instance into a #GParamSpecEnum.
+ */
 #define G_PARAM_SPEC_ENUM(pspec)           (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_ENUM, GParamSpecEnum))
+
+/**
+ * G_TYPE_PARAM_FLAGS:
+ * 
+ * The #GType of #GParamSpecFlags.
+ */
 #define	G_TYPE_PARAM_FLAGS		   (g_param_spec_types[11])
+/**
+ * G_IS_PARAM_SPEC_FLAGS:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_FLAGS.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_IS_PARAM_SPEC_FLAGS(pspec)       (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_FLAGS))
+/**
+ * G_PARAM_SPEC_FLAGS:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Cast a #GParamSpec instance into a #GParamSpecFlags.
+ */
 #define G_PARAM_SPEC_FLAGS(pspec)          (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_FLAGS, GParamSpecFlags))
+
+/**
+ * G_TYPE_PARAM_FLOAT:
+ * 
+ * The #GType of #GParamSpecFloat.
+ */
 #define	G_TYPE_PARAM_FLOAT		   (g_param_spec_types[12])
+/**
+ * G_IS_PARAM_SPEC_FLOAT:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_FLOAT.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_IS_PARAM_SPEC_FLOAT(pspec)       (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_FLOAT))
+/**
+ * G_PARAM_SPEC_FLOAT:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Cast a #GParamSpec instance into a #GParamSpecFloat.
+ */
 #define G_PARAM_SPEC_FLOAT(pspec)          (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_FLOAT, GParamSpecFloat))
+
+/**
+ * G_TYPE_PARAM_DOUBLE:
+ * 
+ * The #GType of #GParamSpecDouble.
+ */
 #define	G_TYPE_PARAM_DOUBLE		   (g_param_spec_types[13])
+/**
+ * G_IS_PARAM_SPEC_DOUBLE:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_DOUBLE.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_IS_PARAM_SPEC_DOUBLE(pspec)      (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_DOUBLE))
+/**
+ * G_PARAM_SPEC_DOUBLE:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Cast a #GParamSpec instance into a #GParamSpecDouble.
+ */
 #define G_PARAM_SPEC_DOUBLE(pspec)         (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_DOUBLE, GParamSpecDouble))
+
+/**
+ * G_TYPE_PARAM_STRING:
+ * 
+ * The #GType of #GParamSpecString.
+ */
 #define	G_TYPE_PARAM_STRING		   (g_param_spec_types[14])
+/**
+ * G_IS_PARAM_SPEC_STRING:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_STRING.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_IS_PARAM_SPEC_STRING(pspec)      (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_STRING))
+/**
+ * G_PARAM_SPEC_STRING:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Casts a #GParamSpec instance into a #GParamSpecString.
+ */
 #define G_PARAM_SPEC_STRING(pspec)         (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_STRING, GParamSpecString))
+
+/**
+ * G_TYPE_PARAM_PARAM:
+ * 
+ * The #GType of #GParamSpecParam.
+ */
 #define	G_TYPE_PARAM_PARAM		   (g_param_spec_types[15])
+/**
+ * G_IS_PARAM_SPEC_PARAM:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_PARAM.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_IS_PARAM_SPEC_PARAM(pspec)       (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_PARAM))
+/**
+ * G_PARAM_SPEC_PARAM:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Casts a #GParamSpec instance into a #GParamSpecParam.
+ */
 #define G_PARAM_SPEC_PARAM(pspec)          (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_PARAM, GParamSpecParam))
+
+/**
+ * G_TYPE_PARAM_BOXED:
+ * 
+ * The #GType of #GParamSpecBoxed.
+ */
 #define	G_TYPE_PARAM_BOXED		   (g_param_spec_types[16])
+/**
+ * G_IS_PARAM_SPEC_BOXED:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_BOXED.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_IS_PARAM_SPEC_BOXED(pspec)       (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_BOXED))
+/**
+ * G_PARAM_SPEC_BOXED:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Cast a #GParamSpec instance into a #GParamSpecBoxed.
+ */
 #define G_PARAM_SPEC_BOXED(pspec)          (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_BOXED, GParamSpecBoxed))
+
+/**
+ * G_TYPE_PARAM_POINTER:
+ * 
+ * The #GType of #GParamSpecPointer.
+ */
 #define	G_TYPE_PARAM_POINTER		   (g_param_spec_types[17])
+/**
+ * G_IS_PARAM_SPEC_POINTER:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_POINTER.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_IS_PARAM_SPEC_POINTER(pspec)     (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_POINTER))
+/**
+ * G_PARAM_SPEC_POINTER:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Casts a #GParamSpec instance into a #GParamSpecPointer.
+ */
 #define G_PARAM_SPEC_POINTER(pspec)        (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_POINTER, GParamSpecPointer))
+
+/**
+ * G_TYPE_PARAM_VALUE_ARRAY:
+ * 
+ * The #GType of #GParamSpecValueArray.
+ */
 #define	G_TYPE_PARAM_VALUE_ARRAY	   (g_param_spec_types[18])
+/**
+ * G_IS_PARAM_SPEC_VALUE_ARRAY:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VALUE_ARRAY.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_IS_PARAM_SPEC_VALUE_ARRAY(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_VALUE_ARRAY))
+/**
+ * G_PARAM_SPEC_VALUE_ARRAY:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Cast a #GParamSpec instance into a #GParamSpecValueArray.
+ */
 #define G_PARAM_SPEC_VALUE_ARRAY(pspec)    (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_VALUE_ARRAY, GParamSpecValueArray))
+
+/**
+ * G_TYPE_PARAM_OBJECT:
+ * 
+ * The #GType of #GParamSpecObject.
+ */
 #define	G_TYPE_PARAM_OBJECT		   (g_param_spec_types[19])
+/**
+ * G_IS_PARAM_SPEC_OBJECT:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_OBJECT.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_IS_PARAM_SPEC_OBJECT(pspec)      (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_OBJECT))
+/**
+ * G_PARAM_SPEC_OBJECT:
+ * @pspec: a valid #GParamSpec instance
+ * 
+ * Casts a #GParamSpec instance into a #GParamSpecObject.
+ */
 #define G_PARAM_SPEC_OBJECT(pspec)         (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_OBJECT, GParamSpecObject))
+
+/**
+ * G_TYPE_PARAM_OVERRIDE:
+ * 
+ * The #GType of #GParamSpecOverride.
+ * 
+ * Since: 2.4
+ */
 #define	G_TYPE_PARAM_OVERRIDE		   (g_param_spec_types[20])
+/**
+ * G_IS_PARAM_SPEC_OVERRIDE:
+ * @pspec: a #GParamSpec
+ * 
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_OVERRIDE.
+ * 
+ * Since: 2.4
+ * Returns: %TRUE on success.
+ */
 #define G_IS_PARAM_SPEC_OVERRIDE(pspec)    (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_OVERRIDE))
+/**
+ * G_PARAM_SPEC_OVERRIDE:
+ * @pspec: a #GParamSpec
+ * 
+ * Casts a #GParamSpec into a #GParamSpecOverride.
+ * 
+ * Since: 2.4
+ */
 #define G_PARAM_SPEC_OVERRIDE(pspec)       (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_OVERRIDE, GParamSpecOverride))
+
+/**
+ * G_TYPE_PARAM_GTYPE:
+ * 
+ * The #GType of #GParamSpecGType.
+ * 
+ * Since: 2.10
+ */
 #define	G_TYPE_PARAM_GTYPE		   (g_param_spec_types[21])
+/**
+ * G_IS_PARAM_SPEC_GTYPE:
+ * @pspec: a #GParamSpec
+ * 
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_GTYPE.
+ * 
+ * Since: 2.10
+ * Returns: %TRUE on success. 
+ */
 #define G_IS_PARAM_SPEC_GTYPE(pspec)       (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_GTYPE))
+/**
+ * G_PARAM_SPEC_GTYPE:
+ * @pspec: a #GParamSpec
+ * 
+ * Casts a #GParamSpec into a #GParamSpecGType.
+ * 
+ * Since: 2.10
+ */
 #define G_PARAM_SPEC_GTYPE(pspec)          (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_GTYPE, GParamSpecGType))
 
 
@@ -125,6 +574,15 @@
 typedef struct _GParamSpecOverride   GParamSpecOverride;
 typedef struct _GParamSpecGType      GParamSpecGType;
 
+/**
+ * GParamSpecChar:
+ * @parent_instance: private #GParamSpec portion
+ * @minimum: minimum value for the property specified
+ * @maximum: maximum value for the property specified
+ * @default_value: default value for the property specified
+ * 
+ * A #GParamSpec derived structure that contains the meta data for character properties.
+ */
 struct _GParamSpecChar
 {
   GParamSpec    parent_instance;
@@ -133,6 +591,15 @@
   gint8         maximum;
   gint8         default_value;
 };
+/**
+ * GParamSpecUChar:
+ * @parent_instance: private #GParamSpec portion
+ * @minimum: minimum value for the property specified
+ * @maximum: maximum value for the property specified
+ * @default_value: default value for the property specified
+ * 
+ * A #GParamSpec derived structure that contains the meta data for unsigned character properties.
+ */
 struct _GParamSpecUChar
 {
   GParamSpec    parent_instance;
@@ -141,12 +608,28 @@
   guint8        maximum;
   guint8        default_value;
 };
+/**
+ * GParamSpecBoolean:
+ * @parent_instance: private #GParamSpec portion
+ * @default_value: default value for the property specified
+ * 
+ * A #GParamSpec derived structure that contains the meta data for boolean properties.
+ */
 struct _GParamSpecBoolean
 {
   GParamSpec    parent_instance;
   
   gboolean      default_value;
 };
+/**
+ * GParamSpecInt:
+ * @parent_instance: private #GParamSpec portion
+ * @minimum: minimum value for the property specified
+ * @maximum: maximum value for the property specified
+ * @default_value: default value for the property specified
+ * 
+ * A #GParamSpec derived structure that contains the meta data for integer properties.
+ */
 struct _GParamSpecInt
 {
   GParamSpec    parent_instance;
@@ -155,6 +638,15 @@
   gint          maximum;
   gint          default_value;
 };
+/**
+ * GParamSpecUInt:
+ * @parent_instance: private #GParamSpec portion
+ * @minimum: minimum value for the property specified
+ * @maximum: maximum value for the property specified
+ * @default_value: default value for the property specified
+ * 
+ * A #GParamSpec derived structure that contains the meta data for unsigned integer properties.
+ */
 struct _GParamSpecUInt
 {
   GParamSpec    parent_instance;
@@ -163,6 +655,15 @@
   guint         maximum;
   guint         default_value;
 };
+/**
+ * GParamSpecLong:
+ * @parent_instance: private #GParamSpec portion
+ * @minimum: minimum value for the property specified
+ * @maximum: maximum value for the property specified
+ * @default_value: default value for the property specified
+ * 
+ * A #GParamSpec derived structure that contains the meta data for long integer properties.
+ */
 struct _GParamSpecLong
 {
   GParamSpec    parent_instance;
@@ -171,6 +672,15 @@
   glong         maximum;
   glong         default_value;
 };
+/**
+ * GParamSpecULong:
+ * @parent_instance: private #GParamSpec portion
+ * @minimum: minimum value for the property specified
+ * @maximum: maximum value for the property specified
+ * @default_value: default value for the property specified
+ * 
+ * A #GParamSpec derived structure that contains the meta data for unsigned long integer properties.
+ */
 struct _GParamSpecULong
 {
   GParamSpec    parent_instance;
@@ -179,6 +689,15 @@
   gulong        maximum;
   gulong        default_value;
 };
+/**
+ * GParamSpecInt64:
+ * @parent_instance: private #GParamSpec portion
+ * @minimum: minimum value for the property specified
+ * @maximum: maximum value for the property specified
+ * @default_value: default value for the property specified
+ * 
+ * A #GParamSpec derived structure that contains the meta data for 64bit integer properties.
+ */
 struct _GParamSpecInt64
 {
   GParamSpec    parent_instance;
@@ -187,6 +706,15 @@
   gint64        maximum;
   gint64        default_value;
 };
+/**
+ * GParamSpecUInt64:
+ * @parent_instance: private #GParamSpec portion
+ * @minimum: minimum value for the property specified
+ * @maximum: maximum value for the property specified
+ * @default_value: default value for the property specified
+ * 
+ * A #GParamSpec derived structure that contains the meta data for unsigned 64bit integer properties.
+ */
 struct _GParamSpecUInt64
 {
   GParamSpec    parent_instance;
@@ -195,12 +723,28 @@
   guint64       maximum;
   guint64       default_value;
 };
+/**
+ * GParamSpecUnichar:
+ * @parent_instance: private #GParamSpec portion
+ * @default_value: default value for the property specified
+ * 
+ * A #GParamSpec derived structure that contains the meta data for unichar (unsigned integer) properties.
+ */
 struct _GParamSpecUnichar
 {
   GParamSpec    parent_instance;
   
   gunichar      default_value;
 };
+/**
+ * GParamSpecEnum:
+ * @parent_instance: private #GParamSpec portion
+ * @enum_class: the #GEnumClass for the enum
+ * @default_value: default value for the property specified
+ * 
+ * A #GParamSpec derived structure that contains the meta data for enum 
+ * properties.
+ */
 struct _GParamSpecEnum
 {
   GParamSpec    parent_instance;
@@ -208,6 +752,15 @@
   GEnumClass   *enum_class;
   gint          default_value;
 };
+/**
+ * GParamSpecFlags:
+ * @parent_instance: private #GParamSpec portion
+ * @flags_class: the #GFlagsClass for the flags
+ * @default_value: default value for the property specified
+ * 
+ * A #GParamSpec derived structure that contains the meta data for flags
+ * properties.
+ */
 struct _GParamSpecFlags
 {
   GParamSpec    parent_instance;
@@ -215,6 +768,17 @@
   GFlagsClass  *flags_class;
   guint         default_value;
 };
+/**
+ * GParamSpecFloat:
+ * @parent_instance: private #GParamSpec portion
+ * @minimum: minimum value for the property specified
+ * @maximum: maximum value for the property specified
+ * @default_value: default value for the property specified
+ * @epsilon: values closer than @epsilon will be considered identical
+ *  by g_param_values_cmp(); the default value is 1e-30.
+ * 
+ * A #GParamSpec derived structure that contains the meta data for float properties.
+ */
 struct _GParamSpecFloat
 {
   GParamSpec    parent_instance;
@@ -224,6 +788,17 @@
   gfloat        default_value;
   gfloat        epsilon;
 };
+/**
+ * GParamSpecDouble:
+ * @parent_instance: private #GParamSpec portion
+ * @minimum: minimum value for the property specified
+ * @maximum: maximum value for the property specified
+ * @default_value: default value for the property specified
+ * @epsilon: values closer than @epsilon will be considered identical
+ *  by g_param_values_cmp(); the default value is 1e-90.
+ * 
+ * A #GParamSpec derived structure that contains the meta data for double properties.
+ */
 struct _GParamSpecDouble
 {
   GParamSpec    parent_instance;
@@ -233,6 +808,19 @@
   gdouble       default_value;
   gdouble       epsilon;
 };
+/**
+ * GParamSpecString:
+ * @parent_instance: private #GParamSpec portion
+ * @default_value: default value for the property specified
+ * @cset_first: a string containing the allowed values for the first byte
+ * @cset_nth: a string containing the allowed values for the subsequent bytes
+ * @substitutor: the replacement byte for bytes which don't match @cset_first or @cset_nth.
+ * @null_fold_if_empty: replace empty string by %NULL
+ * @ensure_non_null: replace %NULL strings by an empty string
+ * 
+ * A #GParamSpec derived structure that contains the meta data for string
+ * properties.
+ */
 struct _GParamSpecString
 {
   GParamSpec    parent_instance;
@@ -244,34 +832,90 @@
   guint         null_fold_if_empty : 1;
   guint         ensure_non_null : 1;
 };
+/**
+ * GParamSpecParam:
+ * @parent_instance: private #GParamSpec portion
+ * 
+ * A #GParamSpec derived structure that contains the meta data for %G_TYPE_PARAM
+ * properties.
+ */
 struct _GParamSpecParam
 {
   GParamSpec    parent_instance;
 };
+/**
+ * GParamSpecBoxed:
+ * @parent_instance: private #GParamSpec portion
+ * 
+ * A #GParamSpec derived structure that contains the meta data for boxed properties.
+ */
 struct _GParamSpecBoxed
 {
   GParamSpec    parent_instance;
 };
+/**
+ * GParamSpecPointer:
+ * @parent_instance: private #GParamSpec portion
+ * 
+ * A #GParamSpec derived structure that contains the meta data for pointer properties.
+ */
 struct _GParamSpecPointer
 {
   GParamSpec    parent_instance;
 };
+/**
+ * GParamSpecValueArray:
+ * @parent_instance: private #GParamSpec portion
+ * @element_spec: a #GParamSpec describing the elements contained in arrays of this property, may be %NULL
+ * @fixed_n_elements: if greater than 0, arrays of this property will always have this many elements
+ * 
+ * A #GParamSpec derived structure that contains the meta data for #GValueArray properties.
+ */
 struct _GParamSpecValueArray
 {
   GParamSpec    parent_instance;
   GParamSpec   *element_spec;
   guint		fixed_n_elements;
 };
+/**
+ * GParamSpecObject:
+ * @parent_instance: private #GParamSpec portion
+ * 
+ * A #GParamSpec derived structure that contains the meta data for object properties.
+ */
 struct _GParamSpecObject
 {
   GParamSpec    parent_instance;
 };
+/**
+ * GParamSpecOverride:
+ * 
+ * This is a type of #GParamSpec type that simply redirects operations to
+ * another paramspec.  All operations other than getting or
+ * setting the value are redirected, including accessing the nick and
+ * blurb, validating a value, and so forth. See
+ * g_param_spec_get_redirect_target() for retrieving the overidden
+ * property. #GParamSpecOverride is used in implementing
+ * g_object_class_override_property(), and will not be directly useful
+ * unless you are implementing a new base type similar to GObject.
+ * 
+ * Since: 2.4
+ */
 struct _GParamSpecOverride
 {
   /*< private >*/
   GParamSpec    parent_instance;
   GParamSpec   *overridden;
 };
+/**
+ * GParamSpecGType:
+ * @parent_instance: private #GParamSpec portion
+ * @is_a_type: a #GType whose subtypes can occur as values
+ * 
+ * A #GParamSpec derived structure that contains the meta data for #GType properties.
+ * 
+ * Since: 2.10
+ */
 struct _GParamSpecGType
 {
   GParamSpec    parent_instance;
@@ -340,7 +984,7 @@
 					  guint64	  maximum,
 					  guint64	  default_value,
 					  GParamFlags	  flags);
-GParamSpec*    g_param_spec_unichar      (const gchar    *name,
+GParamSpec*	g_param_spec_unichar      (const gchar    *name,
 				          const gchar    *nick,
 				          const gchar    *blurb,
 				          gunichar	  default_value,
@@ -400,7 +1044,7 @@
 					  const gchar	 *blurb,
 					  GType		  object_type,
 					  GParamFlags	  flags);
-GParamSpec*     g_param_spec_override    (const gchar    *name,
+GParamSpec*	g_param_spec_override    (const gchar    *name,
 					  GParamSpec     *overridden);
 GParamSpec*	g_param_spec_gtype	 (const gchar	 *name,
 					  const gchar	 *nick,

Modified: trunk/gobject/gvaluetypes.c
==============================================================================
--- trunk/gobject/gvaluetypes.c	(original)
+++ trunk/gobject/gvaluetypes.c	Sat Jun 21 22:16:14 2008
@@ -554,6 +554,13 @@
 
 
 /* --- GValue functions --- */
+/**
+ * g_value_set_char:
+ * @value: a valid #GValue of type %G_TYPE_CHAR
+ * @v_char: character value to be set
+ * 
+ * Set the contents of a %G_TYPE_CHAR #GValue to @v_char.
+ */
 void
 g_value_set_char (GValue *value,
 		  gchar	  v_char)
@@ -563,6 +570,14 @@
   value->data[0].v_int = v_char;
 }
 
+/**
+ * g_value_get_char:
+ * @value: a valid #GValue of type %G_TYPE_CHAR
+ * 
+ * Get the contents of a %G_TYPE_CHAR #GValue.
+ * 
+ * Returns: character contents of @value
+ */
 gchar
 g_value_get_char (const GValue *value)
 {
@@ -571,6 +586,13 @@
   return value->data[0].v_int;
 }
 
+/**
+ * g_value_set_uchar:
+ * @value: a valid #GValue of type %G_TYPE_UCHAR
+ * @v_uchar: unsigned character value to be set
+ * 
+ * Set the contents of a %G_TYPE_UCHAR #GValue to @v_uchar.
+ */
 void
 g_value_set_uchar (GValue *value,
 		   guchar  v_uchar)
@@ -580,6 +602,14 @@
   value->data[0].v_uint = v_uchar;
 }
 
+/**
+ * g_value_get_uchar:
+ * @value: a valid #GValue of type %G_TYPE_UCHAR
+ * 
+ * Get the contents of a %G_TYPE_UCHAR #GValue.
+ * 
+ * Returns: unsigned character contents of @value
+ */
 guchar
 g_value_get_uchar (const GValue *value)
 {
@@ -588,6 +618,13 @@
   return value->data[0].v_uint;
 }
 
+/**
+ * g_value_set_boolean:
+ * @value: a valid #GValue of type %G_TYPE_BOOLEAN
+ * @v_boolean: boolean value to be set
+ * 
+ * Set the contents of a %G_TYPE_BOOLEAN #GValue to @v_boolean.
+ */
 void
 g_value_set_boolean (GValue  *value,
 		     gboolean v_boolean)
@@ -597,6 +634,14 @@
   value->data[0].v_int = v_boolean != FALSE;
 }
 
+/**
+ * g_value_get_boolean:
+ * @value: a valid #GValue of type %G_TYPE_BOOLEAN
+ * 
+ * Get the contents of a %G_TYPE_BOOLEAN #GValue.
+ * 
+ * Returns: boolean contents of @value
+ */
 gboolean
 g_value_get_boolean (const GValue *value)
 {
@@ -605,6 +650,13 @@
   return value->data[0].v_int;
 }
 
+/**
+ * g_value_set_int:
+ * @value: a valid #GValue of type %G_TYPE_INT
+ * @v_int: integer value to be set
+ * 
+ * Set the contents of a %G_TYPE_INT #GValue to @v_int.
+ */
 void
 g_value_set_int (GValue *value,
 		 gint	 v_int)
@@ -614,6 +666,14 @@
   value->data[0].v_int = v_int;
 }
 
+/**
+ * g_value_get_int:
+ * @value: a valid #GValue of type %G_TYPE_INT
+ * 
+ * Get the contents of a %G_TYPE_INT #GValue.
+ * 
+ * Returns: integer contents of @value
+ */
 gint
 g_value_get_int (const GValue *value)
 {
@@ -622,6 +682,13 @@
   return value->data[0].v_int;
 }
 
+/**
+ * g_value_set_uint:
+ * @value: a valid #GValue of type %G_TYPE_UINT
+ * @v_uint: unsigned integer value to be set
+ * 
+ * Set the contents of a %G_TYPE_UINT #GValue to @v_uint.
+ */
 void
 g_value_set_uint (GValue *value,
 		  guint	  v_uint)
@@ -631,6 +698,14 @@
   value->data[0].v_uint = v_uint;
 }
 
+/**
+ * g_value_get_uint:
+ * @value: a valid #GValue of type %G_TYPE_UINT
+ * 
+ * Get the contents of a %G_TYPE_UINT #GValue.
+ * 
+ * Returns: unsigned integer contents of @value
+ */
 guint
 g_value_get_uint (const GValue *value)
 {
@@ -639,6 +714,13 @@
   return value->data[0].v_uint;
 }
 
+/**
+ * g_value_set_long:
+ * @value: a valid #GValue of type %G_TYPE_LONG
+ * @v_long: long integer value to be set
+ * 
+ * Set the contents of a %G_TYPE_LONG #GValue to @v_long.
+ */
 void
 g_value_set_long (GValue *value,
 		  glong	  v_long)
@@ -648,6 +730,14 @@
   value->data[0].v_long = v_long;
 }
 
+/**
+ * g_value_get_long:
+ * @value: a valid #GValue of type %G_TYPE_LONG
+ * 
+ * Get the contents of a %G_TYPE_LONG #GValue.
+ * 
+ * Returns: long integer contents of @value
+ */
 glong
 g_value_get_long (const GValue *value)
 {
@@ -656,6 +746,13 @@
   return value->data[0].v_long;
 }
 
+/**
+ * g_value_set_ulong:
+ * @value: a valid #GValue of type %G_TYPE_ULONG
+ * @v_ulong: unsigned long integer value to be set
+ * 
+ * Set the contents of a %G_TYPE_ULONG #GValue to @v_ulong.
+ */
 void
 g_value_set_ulong (GValue *value,
 		   gulong  v_ulong)
@@ -665,6 +762,14 @@
   value->data[0].v_ulong = v_ulong;
 }
 
+/**
+ * g_value_get_ulong:
+ * @value: a valid #GValue of type %G_TYPE_ULONG
+ * 
+ * Get the contents of a %G_TYPE_ULONG #GValue.
+ * 
+ * Returns: unsigned long integer contents of @value
+ */
 gulong
 g_value_get_ulong (const GValue *value)
 {
@@ -673,6 +778,14 @@
   return value->data[0].v_ulong;
 }
 
+/**
+ * g_value_get_int64:
+ * @value: a valid #GValue of type %G_TYPE_INT64
+ * 
+ * Get the contents of a %G_TYPE_INT64 #GValue.
+ * 
+ * Returns: 64bit integer contents of @value
+ */
 void
 g_value_set_int64 (GValue *value,
 		   gint64  v_int64)
@@ -682,6 +795,13 @@
   value->data[0].v_int64 = v_int64;
 }
 
+/**
+ * g_value_set_int64:
+ * @value: a valid #GValue of type %G_TYPE_INT64
+ * @v_int64: 64bit integer value to be set
+ * 
+ * Set the contents of a %G_TYPE_INT64 #GValue to @v_int64.
+ */
 gint64
 g_value_get_int64 (const GValue *value)
 {
@@ -690,6 +810,13 @@
   return value->data[0].v_int64;
 }
 
+/**
+ * g_value_set_uint64:
+ * @value: a valid #GValue of type %G_TYPE_UINT64
+ * @v_uint64: unsigned 64bit integer value to be set
+ * 
+ * Set the contents of a %G_TYPE_UINT64 #GValue to @v_uint64.
+ */
 void
 g_value_set_uint64 (GValue *value,
 		    guint64 v_uint64)
@@ -699,6 +826,14 @@
   value->data[0].v_uint64 = v_uint64;
 }
 
+/**
+ * g_value_get_uint64:
+ * @value: a valid #GValue of type %G_TYPE_UINT64
+ * 
+ * Get the contents of a %G_TYPE_UINT64 #GValue.
+ * 
+ * Returns: unsigned 64bit integer contents of @value
+ */
 guint64
 g_value_get_uint64 (const GValue *value)
 {
@@ -707,6 +842,13 @@
   return value->data[0].v_uint64;
 }
 
+/**
+ * g_value_set_float:
+ * @value: a valid #GValue of type %G_TYPE_FLOAT
+ * @v_float: float value to be set
+ * 
+ * Set the contents of a %G_TYPE_FLOAT #GValue to @v_float.
+ */
 void
 g_value_set_float (GValue *value,
 		   gfloat  v_float)
@@ -716,6 +858,14 @@
   value->data[0].v_float = v_float;
 }
 
+/**
+ * g_value_get_float:
+ * @value: a valid #GValue of type %G_TYPE_FLOAT
+ * 
+ * Get the contents of a %G_TYPE_FLOAT #GValue.
+ * 
+ * Returns: float contents of @value
+ */
 gfloat
 g_value_get_float (const GValue *value)
 {
@@ -724,6 +874,13 @@
   return value->data[0].v_float;
 }
 
+/**
+ * g_value_set_double:
+ * @value: a valid #GValue of type %G_TYPE_DOUBLE
+ * @v_double: double value to be set
+ * 
+ * Set the contents of a %G_TYPE_DOUBLE #GValue to @v_double.
+ */
 void
 g_value_set_double (GValue *value,
 		    gdouble v_double)
@@ -733,6 +890,14 @@
   value->data[0].v_double = v_double;
 }
 
+/**
+ * g_value_get_double:
+ * @value: a valid #GValue of type %G_TYPE_DOUBLE
+ * 
+ * Get the contents of a %G_TYPE_DOUBLE #GValue.
+ * 
+ * Returns: double contents of @value
+ */
 gdouble
 g_value_get_double (const GValue *value)
 {
@@ -741,6 +906,13 @@
   return value->data[0].v_double;
 }
 
+/**
+ * g_value_set_string:
+ * @value: a valid #GValue of type %G_TYPE_STRING
+ * @v_string: string to be set
+ * 
+ * Set the contents of a %G_TYPE_STRING #GValue to @v_string.
+ */
 void
 g_value_set_string (GValue	*value,
 		    const gchar *v_string)
@@ -759,6 +931,15 @@
   value->data[0].v_pointer = new_val;
 }
 
+/**
+ * g_value_set_static_string:
+ * @value: a valid #GValue of type %G_TYPE_STRING
+ * @v_string: static string to be set
+ * 
+ * Set the contents of a %G_TYPE_STRING #GValue to @v_string.
+ * The string is assumed to be static, and is thus not duplicated
+ * when setting the #GValue.
+ */
 void
 g_value_set_static_string (GValue      *value,
 			   const gchar *v_string)
@@ -771,6 +952,15 @@
   value->data[0].v_pointer = (gchar*) v_string;
 }
 
+/**
+ * g_value_set_string_take_ownership:
+ * @value: a valid #GValue of type %G_TYPE_STRING
+ * @v_string: duplicated unowned string to be set
+ * 
+ * This is an internal function introduced mainly for C marshallers.
+ * 
+ * Deprecated: 2.4: Use g_value_take_string() instead.
+ */
 void
 g_value_set_string_take_ownership (GValue *value,
 				   gchar  *v_string)
@@ -778,6 +968,15 @@
   g_value_take_string (value, v_string);
 }
 
+/**
+ * g_value_take_string:
+ * @value: a valid #GValue of type %G_TYPE_STRING
+ * @v_string: duplicated unowned string to be set
+ * 
+ * Sets the contents of a %G_TYPE_STRING #GValue to @v_string.
+ * 
+ * Since: 2.4
+ */
 void
 g_value_take_string (GValue *value,
 		     gchar  *v_string)
@@ -791,6 +990,14 @@
   value->data[0].v_pointer = v_string;
 }
 
+/**
+ * g_value_get_string:
+ * @value: a valid #GValue of type %G_TYPE_STRING
+ * 
+ * Get the contents of a %G_TYPE_STRING #GValue.
+ * 
+ * Returns: string content of @value
+ */
 G_CONST_RETURN gchar*
 g_value_get_string (const GValue *value)
 {
@@ -799,6 +1006,14 @@
   return value->data[0].v_pointer;
 }
 
+/**
+ * g_value_dup_string:
+ * @value: a valid #GValue of type %G_TYPE_STRING
+ * 
+ * Get a copy the contents of a %G_TYPE_STRING #GValue.
+ * 
+ * Returns: a newly allocated copy of the string content of @value
+ */
 gchar*
 g_value_dup_string (const GValue *value)
 {
@@ -807,6 +1022,13 @@
   return g_strdup (value->data[0].v_pointer);
 }
 
+/**
+ * g_value_set_pointer:
+ * @value: a valid #GValue of %G_TYPE_POINTER
+ * @v_pointer: pointer value to be set
+ * 
+ * Set the contents of a pointer #GValue to @v_pointer.
+ */
 void
 g_value_set_pointer (GValue  *value,
 		     gpointer v_pointer)
@@ -816,6 +1038,14 @@
   value->data[0].v_pointer = v_pointer;
 }
 
+/**
+ * g_value_get_pointer:
+ * @value: a valid #GValue of %G_TYPE_POINTER
+ * 
+ * Get the contents of a pointer #GValue.
+ * 
+ * Returns: pointer contents of @value
+ */
 gpointer
 g_value_get_pointer (const GValue *value)
 {
@@ -834,6 +1064,15 @@
   return type;
 }
 
+/**
+ * g_value_set_gtype:
+ * @value: a valid #GValue of type %G_TYPE_GTYPE
+ * @v_gtype: #GType to be set
+ * 
+ * Set the contents of a %G_TYPE_GTYPE #GValue to @v_gtype.
+ * 
+ * Since: 2.12
+ */
 void 
 g_value_set_gtype (GValue *value,
 		   GType   v_gtype)
@@ -844,6 +1083,15 @@
   
 }
 
+/**
+ * g_value_get_gtype:
+ * @value: a valid #GValue of type %G_TYPE_GTYPE
+ * 
+ * Get the contents of a %G_TYPE_GTYPE #GValue.
+ * 
+ * Since: 2.12
+ * Returns: the #GType stored in @value
+ */
 GType	              
 g_value_get_gtype (const GValue *value)
 {

Modified: trunk/gobject/gvaluetypes.h
==============================================================================
--- trunk/gobject/gvaluetypes.h	(original)
+++ trunk/gobject/gvaluetypes.h	Sat Jun 21 22:16:14 2008
@@ -30,18 +30,122 @@
 G_BEGIN_DECLS
 
 /* --- type macros --- */
+/**
+ * G_VALUE_HOLDS_CHAR:
+ * @value: a valid #GValue structure
+ * 
+ * Checks whether the given #GValue can hold values of type %G_TYPE_CHAR.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_VALUE_HOLDS_CHAR(value)	 (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_CHAR))
+/**
+ * G_VALUE_HOLDS_UCHAR:
+ * @value: a valid #GValue structure
+ * 
+ * Checks whether the given #GValue can hold values of type %G_TYPE_UCHAR.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_VALUE_HOLDS_UCHAR(value)	 (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_UCHAR))
+/**
+ * G_VALUE_HOLDS_BOOLEAN:
+ * @value: a valid #GValue structure
+ * 
+ * Checks whether the given #GValue can hold values of type %G_TYPE_BOOLEAN.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_VALUE_HOLDS_BOOLEAN(value)	 (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_BOOLEAN))
+/**
+ * G_VALUE_HOLDS_INT:
+ * @value: a valid #GValue structure
+ * 
+ * Checks whether the given #GValue can hold values of type %G_TYPE_INT.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_VALUE_HOLDS_INT(value)	 (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_INT))
+/**
+ * G_VALUE_HOLDS_UINT:
+ * @value: a valid #GValue structure
+ * 
+ * Checks whether the given #GValue can hold values of type %G_TYPE_UINT.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_VALUE_HOLDS_UINT(value)	 (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_UINT))
+/**
+ * G_VALUE_HOLDS_LONG:
+ * @value: a valid #GValue structure
+ * 
+ * Checks whether the given #GValue can hold values of type %G_TYPE_LONG.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_VALUE_HOLDS_LONG(value)	 (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_LONG))
+/**
+ * G_VALUE_HOLDS_ULONG:
+ * @value: a valid #GValue structure
+ * 
+ * Checks whether the given #GValue can hold values of type %G_TYPE_ULONG.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_VALUE_HOLDS_ULONG(value)	 (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_ULONG))
+/**
+ * G_VALUE_HOLDS_INT64:
+ * @value: a valid #GValue structure
+ * 
+ * Checks whether the given #GValue can hold values of type %G_TYPE_INT64.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_VALUE_HOLDS_INT64(value)	 (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_INT64))
+/**
+ * G_VALUE_HOLDS_UINT64:
+ * @value: a valid #GValue structure
+ * 
+ * Checks whether the given #GValue can hold values of type %G_TYPE_UINT64.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_VALUE_HOLDS_UINT64(value)	 (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_UINT64))
+/**
+ * G_VALUE_HOLDS_FLOAT:
+ * @value: a valid #GValue structure
+ * 
+ * Checks whether the given #GValue can hold values of type %G_TYPE_FLOAT.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_VALUE_HOLDS_FLOAT(value)	 (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_FLOAT))
+/**
+ * G_VALUE_HOLDS_DOUBLE:
+ * @value: a valid #GValue structure
+ * 
+ * Checks whether the given #GValue can hold values of type %G_TYPE_DOUBLE.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_VALUE_HOLDS_DOUBLE(value)	 (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_DOUBLE))
+/**
+ * G_VALUE_HOLDS_STRING:
+ * @value: a valid #GValue structure
+ * 
+ * Checks whether the given #GValue can hold values of type %G_TYPE_STRING.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_VALUE_HOLDS_STRING(value)	 (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_STRING))
+/**
+ * G_VALUE_HOLDS_POINTER:
+ * @value: a valid #GValue structure
+ * 
+ * Checks whether the given #GValue can hold values of type %G_TYPE_POINTER.
+ * 
+ * Returns: %TRUE on success.
+ */
 #define G_VALUE_HOLDS_POINTER(value)	 (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_POINTER))
 /**
  * G_TYPE_GTYPE:
@@ -49,6 +153,15 @@
  * The type for #GType.
  */
 #define	G_TYPE_GTYPE			 (g_gtype_get_type())
+/**
+ * G_VALUE_HOLDS_GTYPE:
+ * @value: a valid #GValue structure
+ * 
+ * Checks whether the given #GValue can hold values of type %G_TYPE_GTYPE.
+ * 
+ * Since: 2.12
+ * Returns: %TRUE on success.
+ */
 #define G_VALUE_HOLDS_GTYPE(value)	 (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_GTYPE))
 
 
@@ -117,6 +230,11 @@
 
 
 /* humpf, need a C representable type name for G_TYPE_STRING */
+/**
+ * gchararray:
+ * 
+ * A C representable type name for #G_TYPE_STRING.
+ */
 typedef gchar* gchararray;