From: Stefan Kost Date: Sat, 21 Jun 2008 12:45:49 +0000 (+0000) Subject: Migrating docs. X-Git-Tag: GLIB_2_17_3~59 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=0b9bf79ec2f3d27d0816df1f13fe8e8a28c6b138;p=platform%2Fupstream%2Fglib.git Migrating docs. * docs/reference/gobject/tmpl/generic_values.sgml: * gobject/gboxed.h: * gobject/gtype.h: * gobject/gvalue.c: * gobject/gvalue.h: * gobject/gvaluetypes.c: Migrating docs. svn path=/trunk/; revision=7071 --- diff --git a/ChangeLog b/ChangeLog index 70222c7..91e5e65 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,15 @@ 2008-06-21 Stefan Kost + * docs/reference/gobject/tmpl/generic_values.sgml: + * gobject/gboxed.h: + * gobject/gtype.h: + * gobject/gvalue.c: + * gobject/gvalue.h: + * gobject/gvaluetypes.c: + Migrating docs. + +2008-06-21 Stefan Kost + * gobject/genums.h: Fix documentation for return values. diff --git a/docs/reference/gobject/tmpl/generic_values.sgml b/docs/reference/gobject/tmpl/generic_values.sgml deleted file mode 100644 index ec254f4..0000000 --- a/docs/reference/gobject/tmpl/generic_values.sgml +++ /dev/null @@ -1,263 +0,0 @@ - -Generic Values - - -A polymorphic type that can hold values of any other type - - - -The #GValue structure is basically a variable container that consists -of a type identifier and a specific value of that type. -The type identifier within a #GValue structure always determines the -type of the associated value. -To create a undefined #GValue structure, simply create a zero-filled -#GValue structure. To initialize the #GValue, use the g_value_init() -function. A #GValue cannot be used until it is initialized. -The basic type operations (such as freeing and copying) are determined -by the #GTypeValueTable associated with the type ID stored in the #GValue. -Other #GValue operations (such as converting values between types) are -provided by this interface. - - - - -The fundamental types which all support #GValue operations and thus -can be used as a type initializer for g_value_init() are defined by -a separate interface. See the Standard Values -API for details. - - - - - - - -Returns %TRUE if @value holds (or contains) a value of @type. -This macro will also check for @value != %NULL and issue a -warning if the check fails. - - -@value: A #GValue structure. -@type: A #GType value. - - - - -Returns the type identifier of @value. - - -@value: A #GValue structure. - - - - -Returns the type name of @value. - - -@value: A #GValue structure. - - - - -Return whether the passed in type ID can be used for g_value_init(). -That is, this macro checks whether this type provides an implementation -of the #GTypeValueTable functions required for a type to create a #GValue of. - - -@type: A #GType value. -@Returns: Whether @type is suitable as a #GValue type. - - - - -Returns %TRUE if @type is an abstract value type. An abstract value type -introduces a value table, but can't be used for g_value_init() and is normally -used as an abstract base type for derived value types. - - -@type: A #GType value. - - - - -Returns %TRUE if @value is a valid and initialized #GValue structure. - - -@value: A #GValue structure. - - - - -An opaque structure used to hold different types of values. -The data within the structure has protected scope: it is accessible only -to functions within a #GTypeValueTable structure, or implementations of -the g_value_*() API. That is, code portions which implement new fundamental -types. -#GValue users can not make any assumptions about how data is stored -within the 2 element @data union, and the @g_type member should -only be accessed through the G_VALUE_TYPE() macro. - - - - - -Returns the type ID of the "GValue" type which is a boxed type, -used to pass around pointers to GValues. - - - - - - -Returns the type ID of the "GValueArray" type which is a boxed type, -used to pass around pointers to GValueArrays. - - - - - - -Initializes @value with the default value of @type. - - -@value: A zero-filled (uninitialized) #GValue structure. -@g_type: Type the #GValue should hold values of. -@Returns: the #GValue structure that has been passed in - - - - -Copies the value of @src_value into @dest_value. - - -@src_value: An initialized #GValue structure. -@dest_value: An initialized #GValue structure of the same type as @src_value. - - - - -Clears the current value in @value and resets it to the default value -(as if the value had just been initialized). - - -@value: An initialized #GValue structure. -@Returns: the #GValue structure that has been passed in - - - - -Clears the current value in @value and "unsets" the type, -this releases all resources associated with this GValue. -An unset value is the same as an uninitialized (zero-filled) -#GValue structure. - - -@value: An initialized #GValue structure. - - - - -Sets @value from an instantiatable type via the -value_table's collect_value() function. - - -@value: An initialized #GValue structure. -@instance: the instance - - - - -Determines if @value will fit inside the size of a pointer value. -This is an internal function introduced mainly for C marshallers. - - -@value: An initialized #GValue structure. -@Returns: %TRUE if @value will fit inside a pointer value. - - - - -Return the value contents as pointer. This function asserts that -g_value_fits_pointer() returned %TRUE for the passed in value. -This is an internal function introduced mainly for C marshallers. - - -@value: An initialized #GValue structure. -@Returns: %TRUE if @value will fit inside a pointer value. - - - - -Returns whether a #GValue of type @src_type can be copied into -a #GValue of type @dest_type. - - -@src_type: source type to be copied. -@dest_type: destination type for copying. -@Returns: %TRUE if g_value_copy() is possible with @src_type and @dest_type. - - - - -Check whether g_value_transform() is able to transform values -of type @src_type into values of type @dest_type. - - -@src_type: Source type. -@dest_type: Target type. -@Returns: %TRUE if the transformation is possible, %FALSE otherwise. - - - - -Tries to cast the contents of @src_value into a type appropriate -to store in @dest_value, e.g. to transform a %G_TYPE_INT value -into a %G_TYPE_FLOAT value. Performing transformations between -value types might incur precision lossage. Especially -transformations into strings might reveal seemingly arbitrary -results and shouldn't be relied upon for production code (such -as rcfile value or object property serialization). - - -@src_value: Source value. -@dest_value: Target value. -@Returns: Whether a transformation rule was found and could be applied. - Upon failing transformations, @dest_value is left untouched. - - - - -The type of value transformation functions which can be registered with -g_value_register_transform_func(). - - -@src_value: Source value. -@dest_value: Target value. - - - - -Registers a value transformation function for use in g_value_transform(). -A previously registered transformation function for @src_type and @dest_type -will be replaced. - - -@src_type: Source type. -@dest_type: Target type. -@transform_func: a function which transforms values of type @src_type - into value of type @dest_type - - - - -Return a newly allocated string, which describes the contents of a #GValue. -The main purpose of this function is to describe #GValue contents for -debugging output, the way in which the contents are described may change -between different GLib versions. - - -@value: #GValue which contents are to be described. -@Returns: Newly allocated string. - - diff --git a/gobject/gboxed.h b/gobject/gboxed.h index cb9931b..32de024 100644 --- a/gobject/gboxed.h +++ b/gobject/gboxed.h @@ -80,7 +80,19 @@ GType g_boxed_type_register_static (const gchar *name, * The #GType for #GClosure. */ #define G_TYPE_CLOSURE (g_closure_get_type ()) +/** + * G_TYPE_VALUE: + * + * The type ID of the "GValue" type which is a boxed type, + * used to pass around pointers to GValues. + */ #define G_TYPE_VALUE (g_value_get_type ()) +/** + * G_TYPE_VALUE_ARRAY: + * + * The type ID of the "GValueArray" type which is a boxed type, + * used to pass around pointers to GValueArrays. + */ #define G_TYPE_VALUE_ARRAY (g_value_array_get_type ()) /** * G_TYPE_DATE: diff --git a/gobject/gtype.h b/gobject/gtype.h index 5fa9860..a80efc4 100644 --- a/gobject/gtype.h +++ b/gobject/gtype.h @@ -81,6 +81,16 @@ G_BEGIN_DECLS #define G_TYPE_IS_DERIVABLE(type) (g_type_test_flags ((type), G_TYPE_FLAG_DERIVABLE)) #define G_TYPE_IS_DEEP_DERIVABLE(type) (g_type_test_flags ((type), G_TYPE_FLAG_DEEP_DERIVABLE)) #define G_TYPE_IS_ABSTRACT(type) (g_type_test_flags ((type), G_TYPE_FLAG_ABSTRACT)) +/** + * G_TYPE_IS_VALUE_ABSTRACT: + * @type: A #GType value. + * + * Checks if @type is an abstract value type. An abstract value type introduces + * a value table, but can't be used for g_value_init() and is normally used as + * an abstract base type for derived value types. + * + * Returns: %TRUE on success. + */ #define G_TYPE_IS_VALUE_ABSTRACT(type) (g_type_test_flags ((type), G_TYPE_FLAG_VALUE_ABSTRACT)) #define G_TYPE_IS_VALUE_TYPE(type) (g_type_check_is_value_type (type)) #define G_TYPE_HAS_VALUE_TABLE(type) (g_type_value_table_peek (type) != NULL) diff --git a/gobject/gvalue.c b/gobject/gvalue.c index 75ea260..c3a413c 100644 --- a/gobject/gvalue.c +++ b/gobject/gvalue.c @@ -16,6 +16,27 @@ * Free Software Foundation, Inc., 59 Temple Place, Suite 330, * Boston, MA 02111-1307, USA. */ +/** + * SECTION:Generic Values + * @Short_description: A polymorphic type that can hold values of any other type + * @See_also: The fundamental types which all support #GValue operations and + * thus can be used as a type initializer for g_value_init() are defined by + * a separate interface. See the Standard Values + * API for details. + * + * The #GValue structure is basically a variable container that consists + * of a type identifier and a specific value of that type. + * The type identifier within a #GValue structure always determines the + * type of the associated value. + * To create a undefined #GValue structure, simply create a zero-filled + * #GValue structure. To initialize the #GValue, use the g_value_init() + * function. A #GValue cannot be used until it is initialized. + * The basic type operations (such as freeing and copying) are determined + * by the #GTypeValueTable associated with the type ID stored in the #GValue. + * Other #GValue operations (such as converting values between types) are + * provided by this interface. + */ /* * FIXME: MT-safety @@ -66,6 +87,15 @@ value_meminit (GValue *value, memset (value->data, 0, sizeof (value->data)); } +/** + * g_value_init: + * @value: A zero-filled (uninitialized) #GValue structure. + * @g_type: Type the #GValue should hold values of. + * + * Initializes @value with the default value of @type. + * + * Returns: the #GValue structure that has been passed in + */ GValue* g_value_init (GValue *value, GType g_type) @@ -97,6 +127,13 @@ g_value_init (GValue *value, return value; } +/** + * g_value_copy: + * @src_value: An initialized #GValue structure. + * @dest_value: An initialized #GValue structure of the same type as @src_value. + * + * Copies the value of @src_value into @dest_value. + */ void g_value_copy (const GValue *src_value, GValue *dest_value) @@ -120,6 +157,15 @@ g_value_copy (const GValue *src_value, } } +/** + * g_value_reset: + * @value: An initialized #GValue structure. + * + * Clears the current value in @value and resets it to the default value + * (as if the value had just been initialized). + * + * Returns: the #GValue structure that has been passed in + */ GValue* g_value_reset (GValue *value) { @@ -142,6 +188,15 @@ g_value_reset (GValue *value) return value; } +/** + * g_value_unset: + * @value: An initialized #GValue structure. + * + * Clears the current value in @value and "unsets" the type, + * this releases all resources associated with this GValue. + * An unset value is the same as an uninitialized (zero-filled) + * #GValue structure. + */ void g_value_unset (GValue *value) { @@ -156,6 +211,15 @@ g_value_unset (GValue *value) memset (value, 0, sizeof (*value)); } +/** + * g_value_fits_pointer: + * @value: An initialized #GValue structure. + * + * Determines if @value will fit inside the size of a pointer value. + * This is an internal function introduced mainly for C marshallers. + * + * Returns: %TRUE if @value will fit inside a pointer value. + */ gboolean g_value_fits_pointer (const GValue *value) { @@ -168,6 +232,16 @@ g_value_fits_pointer (const GValue *value) return value_table->value_peek_pointer != NULL; } +/** + * g_value_peek_pointer: + * @value: An initialized #GValue structure. + * + * Return the value contents as pointer. This function asserts that + * g_value_fits_pointer() returned %TRUE for the passed in value. + * This is an internal function introduced mainly for C marshallers. + * + * Returns: %TRUE if @value will fit inside a pointer value. + */ gpointer g_value_peek_pointer (const GValue *value) { @@ -185,6 +259,14 @@ g_value_peek_pointer (const GValue *value) return value_table->value_peek_pointer (value); } +/** + * g_value_set_instance: + * @value: An initialized #GValue structure. + * @instance: the instance + * + * Sets @value from an instantiatable type via the + * value_table's collect_value() function. + */ void g_value_set_instance (GValue *value, gpointer instance) @@ -276,6 +358,17 @@ transform_entries_cmp (gconstpointer bsearch_node1, return G_BSEARCH_ARRAY_CMP (e1->dest_type, e2->dest_type); } +/** + * g_value_register_transform_func: + * @src_type: Source type. + * @dest_type: Target type. + * @transform_func: a function which transforms values of type @src_type + * into value of type @dest_type + * + * Registers a value transformation function for use in g_value_transform(). + * A previously registered transformation function for @src_type and @dest_type + * will be replaced. + */ void g_value_register_transform_func (GType src_type, GType dest_type, @@ -304,6 +397,16 @@ g_value_register_transform_func (GType src_type, transform_array = g_bsearch_array_replace (transform_array, &transform_bconfig, &entry); } +/** + * g_value_type_transformable: + * @src_type: Source type. + * @dest_type: Target type. + * + * Check whether g_value_transform() is able to transform values + * of type @src_type into values of type @dest_type. + * + * Returns: %TRUE if the transformation is possible, %FALSE otherwise. + */ gboolean g_value_type_transformable (GType src_type, GType dest_type) @@ -315,6 +418,16 @@ g_value_type_transformable (GType src_type, transform_func_lookup (src_type, dest_type) != NULL); } +/** + * g_value_type_compatible: + * @src_type: source type to be copied. + * @dest_type: destination type for copying. + * + * Returns whether a #GValue of type @src_type can be copied into + * a #GValue of type @dest_type. + * + * Returns: %TRUE if g_value_copy() is possible with @src_type and @dest_type. + */ gboolean g_value_type_compatible (GType src_type, GType dest_type) @@ -326,6 +439,22 @@ g_value_type_compatible (GType src_type, g_type_value_table_peek (dest_type) == g_type_value_table_peek (src_type)); } +/** + * g_value_transform: + * @src_value: Source value. + * @dest_value: Target value. + * + * Tries to cast the contents of @src_value into a type appropriate + * to store in @dest_value, e.g. to transform a %G_TYPE_INT value + * into a %G_TYPE_FLOAT value. Performing transformations between + * value types might incur precision lossage. Especially + * transformations into strings might reveal seemingly arbitrary + * results and shouldn't be relied upon for production code (such + * as rcfile value or object property serialization). + * + * Returns: Whether a transformation rule was found and could be applied. + * Upon failing transformations, @dest_value is left untouched. + */ gboolean g_value_transform (const GValue *src_value, GValue *dest_value) diff --git a/gobject/gvalue.h b/gobject/gvalue.h index b93e1e9..b3f2872 100644 --- a/gobject/gvalue.h +++ b/gobject/gvalue.h @@ -30,16 +30,81 @@ G_BEGIN_DECLS /* --- type macros --- */ +/** + * G_TYPE_IS_VALUE: + * @type: A #GType value. + * + * Checks whether the passed in type ID can be used for g_value_init(). + * That is, this macro checks whether this type provides an implementation + * of the #GTypeValueTable functions required for a type to create a #GValue of. + * + * Returns: Whether @type is suitable as a #GValue type. + */ #define G_TYPE_IS_VALUE(type) (g_type_check_is_value_type (type)) +/** + * G_IS_VALUE: + * @value: A #GValue structure. + * + * Checks if @value is a valid and initialized #GValue structure. + * + * Returns: %TRUE on success. + */ #define G_IS_VALUE(value) (G_TYPE_CHECK_VALUE (value)) +/** + * G_VALUE_TYPE: + * @value: A #GValue structure. + * + * Get the type identifier of @value. + * + * Returns: the #GType. + */ #define G_VALUE_TYPE(value) (((GValue*) (value))->g_type) +/** + * G_VALUE_TYPE_NAME: + * @value: A #GValue structure. + * + * Gets the the type name of @value. + * + * Returns: the type name. + */ #define G_VALUE_TYPE_NAME(value) (g_type_name (G_VALUE_TYPE (value))) +/** + * G_VALUE_HOLDS: + * @value: A #GValue structure. + * @type: A #GType value. + * + * Checks if @value holds (or contains) a value of @type. + * This macro will also check for @value != %NULL and issue a + * warning if the check fails. + * + * Returns: %TRUE if @value holds the @type. + */ #define G_VALUE_HOLDS(value,type) (G_TYPE_CHECK_VALUE_TYPE ((value), (type))) /* --- typedefs & structures --- */ +/** + * GValueTransform: + * @src_value: Source value. + * @dest_value: Target value. + * + * The type of value transformation functions which can be registered with + * g_value_register_transform_func(). + */ typedef void (*GValueTransform) (const GValue *src_value, GValue *dest_value); +/** + * GValue: + * + * An opaque structure used to hold different types of values. + * The data within the structure has protected scope: it is accessible only + * to functions within a #GTypeValueTable structure, or implementations of + * the g_value_*() API. That is, code portions which implement new fundamental + * types. + * #GValue users can not make any assumptions about how data is stored + * within the 2 element @data union, and the @g_type member should + * only be accessed through the G_VALUE_TYPE() macro. + */ struct _GValue { /*< private >*/ diff --git a/gobject/gvaluetypes.c b/gobject/gvaluetypes.c index 6b145e1..5da1eba 100644 --- a/gobject/gvaluetypes.c +++ b/gobject/gvaluetypes.c @@ -852,7 +852,17 @@ g_value_get_gtype (const GValue *value) return value->data[0].v_long; } - +/** + * g_strdup_value_contents: + * @value: #GValue which contents are to be described. + * + * Return a newly allocated string, which describes the contents of a #GValue. + * The main purpose of this function is to describe #GValue contents for + * debugging output, the way in which the contents are described may change + * between different GLib versions. + * + * Returns: Newly allocated string. + */ gchar* g_strdup_value_contents (const GValue *value) {