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

[stefkost svn gnome org]

Author: stefkost
Date: Sat Jun 21 10:19:58 2008
New Revision: 7065
URL: http://svn.gnome.org/viewvc/glib?rev=7065&view=rev

Log:
	* docs/reference/gobject/tmpl/gboxed.sgml:
	* gobject/gboxed.c:
	* gobject/gboxed.h:
	* gobject/gvaluetypes.c:
	  Migrating docs.



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

Modified: trunk/gobject/gboxed.c
==============================================================================
--- trunk/gobject/gboxed.c	(original)
+++ trunk/gobject/gboxed.c	Sat Jun 21 10:19:58 2008
@@ -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 @@
   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 @@
   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 @@
   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)

Modified: trunk/gobject/gboxed.h
==============================================================================
--- trunk/gobject/gboxed.h	(original)
+++ trunk/gobject/gboxed.h	Sat Jun 21 10:19:58 2008
@@ -33,8 +33,25 @@
 
 
 /* --- 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 @@
 #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_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

Modified: trunk/gobject/gvaluetypes.c
==============================================================================
--- trunk/gobject/gvaluetypes.c	(original)
+++ trunk/gobject/gvaluetypes.c	Sat Jun 21 10:19:58 2008
@@ -915,6 +915,15 @@
   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)
 {