From: Stefan Kost Date: Sat, 21 Jun 2008 10:19:58 +0000 (+0000) Subject: Migrating docs. X-Git-Url: http://git.openbox.org/?a=commitdiff_plain;h=86a0f779f68f31452d3293bfddcbe8fd249ab5ab;p=dana%2Fcg-glib.git Migrating docs. * docs/reference/gobject/tmpl/gboxed.sgml: * gobject/gboxed.c: * gobject/gboxed.h: * gobject/gvaluetypes.c: Migrating docs. svn path=/trunk/; revision=7065 --- diff --git a/ChangeLog b/ChangeLog index 58b58183..85a612d1 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,11 @@ +2008-06-21 Stefan Kost + + * docs/reference/gobject/tmpl/gboxed.sgml: + * gobject/gboxed.c: + * gobject/gboxed.h: + * gobject/gvaluetypes.c: + Migrating docs. + 2008-06-20 Sebastian Dröge Bug 316221 - G_LOCK warns about breaking strict-aliasing rules diff --git a/docs/reference/gobject/tmpl/gboxed.sgml b/docs/reference/gobject/tmpl/gboxed.sgml deleted file mode 100644 index 060f01dd..00000000 --- a/docs/reference/gobject/tmpl/gboxed.sgml +++ /dev/null @@ -1,155 +0,0 @@ - -GBoxed - - -A mechanism to wrap opaque C structures registered by the type system - - - -GBoxed is a generic wrapper mechanism for arbitrary C structures. The only -thing the type system needs to know about the structures is how to copy and -free them, beyond that they are treated as opaque chunks of memory. - - -Boxed types are useful for simple value-holder structures like rectangles or -points. They can also be used for wrapping structures defined in non-GObject -based libraries. - - - - -#GParamSpecBoxed, g_param_spec_boxed() - - - - - - - -This function is provided by the user and should produce a copy of the passed -in boxed structure. - - -@boxed: The boxed structure to be copied. -@Returns: The newly created copy of the boxed structure. - - - - -This function is provided by the user and should free the boxed -structure passed. - - -@boxed: The boxed structure to be freed. - - - - -Provide a copy of a boxed structure @src_boxed which is of type @boxed_type. - - -@boxed_type: The type of @src_boxed. -@src_boxed: The boxed structure to be copied. -@Returns: The newly created copy of the boxed structure. - - - - -Free the boxed structure @boxed which is of type @boxed_type. - - -@boxed_type: The type of @boxed. -@boxed: The boxed structure to be freed. - - - - -This function creates a new %G_TYPE_BOXED derived type id for a new -boxed type with name @name. Boxed type handling functions have to be -provided to copy and free opaque boxed structures of this type. - - -@name: Name of the new boxed type. -@boxed_copy: Boxed structure copy function. -@boxed_free: Boxed structure free function. -@Returns: New %G_TYPE_BOXED derived type id for @name. - - - - -Creates a new %G_TYPE_POINTER derived type id for a new -pointer type with name @name. - - -@name: the name of the new pointer type. -@Returns: a new %G_TYPE_POINTER derived type id for @name. - - - - -The #GType for a boxed type holding a #GHashTable reference. - - -@Since: 2.10 - - - - -The #GType for #GDate. - - - - - - -The #GType for #GString. - - - - - - -The #GType for a boxed type holding a %NULL-terminated array of strings. - - -The code fragments in the following example show the use of a property of -type #G_TYPE_STRV with g_object_class_install_property(), g_object_set() -and g_object_get(). - - -g_object_class_install_property (object_class, - PROP_AUTHORS, - g_param_spec_boxed ("authors", - _("Authors"), - _("List of authors"), - G_TYPE_STRV, - G_PARAM_READWRITE)); - - -gchar *authors[] = { "Owen", "Tim", NULL }; -g_object_set (obj, "authors", authors, NULL); - - -gchar *writers[]; -g_object_get (obj, "authors", &writers, NULL); -/* do something with writers */ -g_strfreev (writers); - - -@Since: 2.4 - - - - -The #GType for a boxed type holding a #GRegex reference. - - -@Since: 2.14 - - - - -A C representable type name for #G_TYPE_STRV. - - - diff --git a/gobject/gboxed.c b/gobject/gboxed.c index 8296c116..a4b09df0 100644 --- a/gobject/gboxed.c +++ b/gobject/gboxed.c @@ -16,6 +16,20 @@ * Free Software Foundation, Inc., 59 Temple Place, Suite 330, * Boston, MA 02111-1307, USA. */ +/** + * SECTION:GBoxed + * @Short_description: A mechanism to wrap opaque C structures registered by the type system + * @See_also:#GParamSpecBoxed, g_param_spec_boxed() + * + * GBoxed is a generic wrapper mechanism for arbitrary C structures. The only + * thing the type system needs to know about the structures is how to copy and + * free them, beyond that they are treated as opaque chunks of memory. + * + * Boxed types are useful for simple value-holder structures like rectangles or + * points. They can also be used for wrapping structures defined in non-GObject + * based libraries. + */ + #include "gboxed.h" #include "gbsearcharray.h" @@ -347,6 +361,18 @@ boxed_proxy_lcopy_value (const GValue *value, return NULL; } +/** + * g_boxed_type_register_static: + * @name: Name of the new boxed type. + * @boxed_copy: Boxed structure copy function. + * @boxed_free: Boxed structure free function. + * + * This function creates a new %G_TYPE_BOXED derived type id for a new + * boxed type with name @name. Boxed type handling functions have to be + * provided to copy and free opaque boxed structures of this type. + * + * Returns: New %G_TYPE_BOXED derived type id for @name. + */ GType g_boxed_type_register_static (const gchar *name, GBoxedCopyFunc boxed_copy, @@ -397,6 +423,15 @@ g_boxed_type_register_static (const gchar *name, return type; } +/** + * g_boxed_copy: + * @boxed_type: The type of @src_boxed. + * @src_boxed: The boxed structure to be copied. + * + * Provide a copy of a boxed structure @src_boxed which is of type @boxed_type. + * + * Returns: The newly created copy of the boxed structure. + */ gpointer g_boxed_copy (GType boxed_type, gconstpointer src_boxed) @@ -455,6 +490,13 @@ g_boxed_copy (GType boxed_type, return dest_boxed; } +/** + * g_boxed_free: + * @boxed_type: The type of @boxed. + * @boxed: The boxed structure to be freed. + * + * Free the boxed structure @boxed which is of type @boxed_type. + */ void g_boxed_free (GType boxed_type, gpointer boxed) diff --git a/gobject/gboxed.h b/gobject/gboxed.h index 622b1e76..5031ab13 100644 --- a/gobject/gboxed.h +++ b/gobject/gboxed.h @@ -33,8 +33,25 @@ G_BEGIN_DECLS /* --- typedefs --- */ -typedef gpointer (*GBoxedCopyFunc) (gpointer boxed); -typedef void (*GBoxedFreeFunc) (gpointer boxed); +/** + * GBoxedCopyFunc: + * @boxed: The boxed structure to be copied. + * + * This function is provided by the user and should produce a copy of the passed + * in boxed structure. + * + * Returns: The newly created copy of the boxed structure. + */ +typedef gpointer (*GBoxedCopyFunc) (gpointer boxed); + +/** + * GBoxedFreeFunc: + * @boxed: The boxed structure to be freed. + * + * This function is provided by the user and should free the boxed + * structure passed. + */ +typedef void (*GBoxedFreeFunc) (gpointer boxed); /* --- prototypes --- */ @@ -60,11 +77,66 @@ GType g_boxed_type_register_static (const gchar *name, #define G_TYPE_CLOSURE (g_closure_get_type ()) #define G_TYPE_VALUE (g_value_get_type ()) #define G_TYPE_VALUE_ARRAY (g_value_array_get_type ()) +/** + * G_TYPE_DATE: + * + * The #GType for #GDate. + */ #define G_TYPE_DATE (g_date_get_type ()) +/** + * G_TYPE_STRV: + * + * The #GType for a boxed type holding a %NULL-terminated array of strings. + * + * The code fragments in the following example show the use of a property of + * type #G_TYPE_STRV with g_object_class_install_property(), g_object_set() + * and g_object_get(). + * + * |[ + * g_object_class_install_property (object_class, + * PROP_AUTHORS, + * g_param_spec_boxed ("authors", + * _("Authors"), + * _("List of authors"), + * G_TYPE_STRV, + * G_PARAM_READWRITE)); + * + * + * gchar *authors[] = { "Owen", "Tim", NULL }; + * g_object_set (obj, "authors", authors, NULL); + * + * + * gchar *writers[]; + * g_object_get (obj, "authors", &writers, NULL); + * // do something with writers + * g_strfreev (writers); + * ]| + * + * Since: 2.4 + */ #define G_TYPE_STRV (g_strv_get_type ()) +/** + * G_TYPE_GSTRING: + * + * The #GType for #GString. + */ #define G_TYPE_GSTRING (g_gstring_get_type ()) -#define G_TYPE_HASH_TABLE (g_hash_table_get_type ()) -#define G_TYPE_REGEX (g_regex_get_type ()) +/** + * G_TYPE_HASH_TABLE: + * + * The #GType for a boxed type holding a #GHashTable reference. + * + * Since: 2.10 + */ +#define G_TYPE_HASH_TABLE (g_hash_table_get_type ()) +/** + * G_TYPE_REGEX: + * + * The #GType for a boxed type holding a #GRegex reference. + * + * Since: 2.14 + */ +#define G_TYPE_REGEX (g_regex_get_type ()) void g_value_take_boxed (GValue *value, @@ -82,6 +154,11 @@ GType g_gstring_get_type (void) G_GNUC_CONST; GType g_hash_table_get_type (void) G_GNUC_CONST; GType g_regex_get_type (void) G_GNUC_CONST; +/** + * GStrv: + * + * A C representable type name for #G_TYPE_STRV. + */ typedef gchar** GStrv; G_END_DECLS diff --git a/gobject/gvaluetypes.c b/gobject/gvaluetypes.c index a479a580..6b145e15 100644 --- a/gobject/gvaluetypes.c +++ b/gobject/gvaluetypes.c @@ -915,6 +915,15 @@ g_strdup_value_contents (const GValue *value) return contents; } +/** + * g_pointer_type_register_static: + * @name: the name of the new pointer type. + * + * Creates a new %G_TYPE_POINTER derived type id for a new + * pointer type with name @name. + * + * Returns: a new %G_TYPE_POINTER derived type id for @name. + */ GType g_pointer_type_register_static (const gchar *name) {