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 58b5818..85a612d 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2008-06-21  Stefan Kost  <ensonic@users.sf.net>
+
+       * docs/reference/gobject/tmpl/gboxed.sgml:
+       * gobject/gboxed.c:
+       * gobject/gboxed.h:
+       * gobject/gvaluetypes.c:
+         Migrating docs.
+
 2008-06-20  Sebastian Dröge  <slomo@circular-chaos.org>
 
        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 (file)
index 060f01d..0000000
--- a/docs/reference/gobject/tmpl/gboxed.sgml
+++ /dev/null
@@ -1,155 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-GBoxed
-
-<!-- ##### SECTION Short_Description ##### -->
-A mechanism to wrap opaque C structures registered by the type system
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-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.
-</para>
-<para>
-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.
-</para>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-#GParamSpecBoxed, g_param_spec_boxed()
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### USER_FUNCTION GBoxedCopyFunc ##### -->
-<para>
-This function is provided by the user and should produce a copy of the passed
-in boxed structure.
-</para>
-
-@boxed:   The boxed structure to be copied.
-@Returns: The newly created copy of the boxed structure.
-
-
-<!-- ##### USER_FUNCTION GBoxedFreeFunc ##### -->
-<para>
-This function is provided by the user and should free the boxed
-structure passed.
-</para>
-
-@boxed: The boxed structure to be freed.
-
-
-<!-- ##### FUNCTION g_boxed_copy ##### -->
-<para>
-Provide a copy of a boxed structure @src_boxed which is of type @boxed_type.
-</para>
-
-@boxed_type: The type of @src_boxed.
-@src_boxed:  The boxed structure to be copied.
-@Returns:    The newly created copy of the boxed structure.
-
-
-<!-- ##### FUNCTION g_boxed_free ##### -->
-<para>
-Free the boxed structure @boxed which is of type @boxed_type.
-</para>
-
-@boxed_type: The type of @boxed.
-@boxed:      The boxed structure to be freed.
-
-
-<!-- ##### FUNCTION g_boxed_type_register_static ##### -->
-<para>
-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.
-</para>
-
-@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.
-
-
-<!-- ##### FUNCTION g_pointer_type_register_static ##### -->
-<para>
-Creates a new %G_TYPE_POINTER derived type id for a new
-pointer type with name @name. 
-</para>
-
-@name: the name of the new pointer type.
-@Returns: a new %G_TYPE_POINTER derived type id for @name.
-
-
-<!-- ##### MACRO G_TYPE_HASH_TABLE ##### -->
-<para>
-The #GType for a boxed type holding a #GHashTable reference.
-</para>
-
-@Since: 2.10
-
-
-<!-- ##### MACRO G_TYPE_DATE ##### -->
-<para>
-The #GType for #GDate.
-</para>
-
-
-
-<!-- ##### MACRO G_TYPE_GSTRING ##### -->
-<para>
-The #GType for #GString.
-</para>
-
-
-
-<!-- ##### MACRO G_TYPE_STRV ##### -->
-<para>
-The #GType for a boxed type holding a %NULL-terminated array of strings.
-</para>
-<para>
-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().
-</para>
-<informalexample><programlisting>
-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", &amp;writers, NULL);
-/* do something with writers */
-g_strfreev (writers);
-</programlisting></informalexample>
-
-@Since: 2.4
-
-
-<!-- ##### MACRO G_TYPE_REGEX ##### -->
-<para>
-The #GType for a boxed type holding a #GRegex reference.
-</para>
-
-@Since: 2.14
-
-
-<!-- ##### TYPEDEF GStrv ##### -->
-<para>
-A C representable type name for #G_TYPE_STRV.
-</para>
-
-

diff --git a/gobject/gboxed.c b/gobject/gboxed.c
index 8296c11..a4b09df 100644 (file)
--- 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 622b1e7..5031ab1 100644 (file)
--- 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 a479a58..6b145e1 100644 (file)
--- 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)
 {