GNOME.org
 

[glib/gsettings: 6/327] Generate gtk-doc for GVariant

commit 654b4857c04e8602634b86a1351e204c2627cf5f
Author: Ryan Lortie <desrt desrt ca>
Date:   Mon Apr 6 12:57:31 2009 -0400

    Generate gtk-doc for GVariant
    
    Also, clean up some of the documentation in the code itself.

 docs/reference/glib/Makefile.am       |    5 +-
 docs/reference/glib/glib-docs.sgml    |    5 +
 docs/reference/glib/glib-sections.txt |  173 ++++++++++++++++++++++++++++
 docs/reference/glib/tmpl/threads.sgml |   18 +++
 glib/gvariant-valist.c                |  204 +++++++++++++++++++++++++++++++--
 glib/gvarianttype.c                   |   24 +++-
 glib/gvarianttype.h                   |   12 +-
 7 files changed, 421 insertions(+), 20 deletions(-)
---
diff --git a/docs/reference/glib/Makefile.am b/docs/reference/glib/Makefile.am
index c7b9feb..12dc63c 100644
--- a/docs/reference/glib/Makefile.am
+++ b/docs/reference/glib/Makefile.am
@@ -45,7 +45,10 @@ IGNORE_HFILES=			\
 	glib-mirroring-tab	\
 	gnulib			\
 	pcre			\
-	update-pcre
+	update-pcre		\
+	gvariant-serialiser.h	\
+	gvariant-private.h	\
+	gvarianttypeinfo.h
 
 # Images to copy into HTML directory
 HTML_IMAGES =  				\
diff --git a/docs/reference/glib/glib-docs.sgml b/docs/reference/glib/glib-docs.sgml
index cef6e8c..e1eb902 100644
--- a/docs/reference/glib/glib-docs.sgml
+++ b/docs/reference/glib/glib-docs.sgml
@@ -67,6 +67,9 @@
 <!ENTITY glib-Uri SYSTEM "xml/gurifuncs.xml">
 <!ENTITY glib-Testing SYSTEM "xml/testing.xml">
 
+<!ENTITY glib-GVariantType SYSTEM "xml/gvarianttype.xml">
+<!ENTITY glib-GVariant SYSTEM "xml/gvariant.xml">
+
 <!ENTITY glib-Compiling SYSTEM "compiling.sgml">
 <!ENTITY glib-Building SYSTEM "building.sgml">
 <!ENTITY glib-Cross SYSTEM "cross.sgml">
@@ -196,6 +199,8 @@ synchronize their operation.
     &glib-Relations-and-Tuples;
     &glib-Caches;
     &glib-Memory-Allocators;
+    &glib-GVariantType;
+    &glib-GVariant;
   </chapter>
 
   <chapter id="tools">
diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt
index 00da15d..ba901f8 100644
--- a/docs/reference/glib/glib-sections.txt
+++ b/docs/reference/glib/glib-sections.txt
@@ -2657,3 +2657,176 @@ g_test_log_buffer_push
 g_test_log_buffer_pop
 g_test_log_msg_free
 </SECTION>
+
+<SECTION>
+<TITLE>GVariantType</TITLE>
+<FILE>gvarianttype</FILE>
+GVariantTypeClass
+g_variant_type_class_is_basic
+g_variant_type_class_is_container
+
+<SUBSECTION>
+GVariantType
+G_VARIANT_TYPE
+
+<SUBSECTION>
+G_VARIANT_TYPE_BOOLEAN
+G_VARIANT_TYPE_BYTE
+G_VARIANT_TYPE_INT16
+G_VARIANT_TYPE_UINT16
+G_VARIANT_TYPE_INT32
+G_VARIANT_TYPE_UINT32
+G_VARIANT_TYPE_INT64
+G_VARIANT_TYPE_UINT64
+G_VARIANT_TYPE_DOUBLE
+G_VARIANT_TYPE_STRING
+G_VARIANT_TYPE_OBJECT_PATH
+G_VARIANT_TYPE_SIGNATURE
+G_VARIANT_TYPE_VARIANT
+G_VARIANT_TYPE_ANY
+G_VARIANT_TYPE_ANY_BASIC
+G_VARIANT_TYPE_ANY_MAYBE
+G_VARIANT_TYPE_ANY_ARRAY
+G_VARIANT_TYPE_ANY_STRUCT
+G_VARIANT_TYPE_UNIT
+G_VARIANT_TYPE_ANY_DICT_ENTRY
+G_VARIANT_TYPE_ANY_DICTIONARY
+
+<SUBSECTION>
+g_variant_type_free
+g_variant_type_copy
+g_variant_type_new
+
+<SUBSECTION>
+g_variant_type_string_is_valid
+g_variant_type_string_scan
+g_variant_type_get_string_length
+g_variant_type_peek_string
+g_variant_type_dup_string
+
+<SUBSECTION>
+g_variant_type_get_class
+g_variant_type_is_in_class
+g_variant_type_is_basic
+g_variant_type_is_container
+g_variant_type_is_concrete
+
+<SUBSECTION>
+g_variant_type_hash
+g_variant_type_equal
+g_variant_type_matches
+
+<SUBSECTION>
+g_variant_type_new_maybe
+g_variant_type_new_array
+GVariantTypeGetter
+g_variant_type_new_struct
+g_variant_type_new_dict_entry
+
+<SUBSECTION>
+g_variant_type_element
+g_variant_type_n_items
+g_variant_type_first
+g_variant_type_next
+g_variant_type_key
+g_variant_type_value
+</SECTION>
+
+<SECTION>
+<TITLE>GVariant</TITLE>
+<FILE>gvariant</FILE>
+GVariant
+g_variant_ref
+g_variant_ref_sink
+g_variant_unref
+g_variant_get_type
+g_variant_get_type_class
+g_variant_matches
+g_variant_get_type_string
+g_variant_is_basic
+g_variant_is_container
+
+<SUBSECTION>
+g_variant_new_boolean
+g_variant_new_byte
+g_variant_new_int16
+g_variant_new_uint16
+g_variant_new_int32
+g_variant_new_uint32
+g_variant_new_int64
+g_variant_new_uint64
+g_variant_new_double
+g_variant_new_string
+g_variant_new_object_path
+g_variant_is_object_path
+g_variant_new_signature
+g_variant_is_signature
+g_variant_new_variant
+
+<SUBSECTION>
+g_variant_get_boolean
+g_variant_get_byte
+g_variant_get_int16
+g_variant_get_uint16
+g_variant_get_int32
+g_variant_get_uint32
+g_variant_get_int64
+g_variant_get_uint64
+g_variant_get_double
+g_variant_get_string
+g_variant_dup_string
+g_variant_get_variant
+
+<SUBSECTION>
+g_variant_n_children
+g_variant_get_child
+g_variant_get_fixed
+g_variant_get_fixed_array
+
+<SUBSECTION>
+g_variant_get
+g_variant_get_va
+g_variant_new
+g_variant_new_va
+g_variant_format_string_scan
+
+<SUBSECTION>
+GVariantIter
+g_variant_iter_cancel
+g_variant_iter_init
+g_variant_iter_next
+g_variant_iter_was_cancelled
+g_variant_iterate
+
+<SUBSECTION>
+GVariantBuilder
+g_variant_builder_add_value
+g_variant_builder_cancel
+g_variant_builder_close
+g_variant_builder_end
+g_variant_builder_new
+g_variant_builder_open
+g_variant_builder_add
+G_VARIANT_BUILDER_ERROR
+GVariantBuilderError
+g_variant_builder_check_add
+g_variant_builder_check_end
+
+<SUBSECTION>
+g_variant_markup_parse
+g_variant_markup_parse_context_end
+g_variant_markup_parse_context_new
+g_variant_markup_print
+g_variant_markup_subparser_end
+g_variant_markup_subparser_start
+
+<SUBSECTION>
+GVariantFlags
+g_variant_load
+g_variant_store
+g_variant_flatten
+g_variant_from_data
+g_variant_from_slice
+g_variant_get_data
+g_variant_get_size
+</SECTION>
diff --git a/docs/reference/glib/tmpl/threads.sgml b/docs/reference/glib/tmpl/threads.sgml
index 3ee9d61..62cd69b 100644
--- a/docs/reference/glib/tmpl/threads.sgml
+++ b/docs/reference/glib/tmpl/threads.sgml
@@ -1796,3 +1796,21 @@ variable.
 @Since: 2.14
 
 
+<!-- ##### FUNCTION g_bit_lock ##### -->
+<para>
+
+</para>
+
+ lock: 
+ lock_bit: 
+
+
+<!-- ##### FUNCTION g_bit_unlock ##### -->
+<para>
+
+</para>
+
+ lock: 
+ lock_bit: 
+
+
diff --git a/glib/gvariant-valist.c b/glib/gvariant-valist.c
index 58279fb..16a629f 100644
--- a/glib/gvariant-valist.c
+++ b/glib/gvariant-valist.c
@@ -742,8 +742,9 @@ g_variant_valist_get (GVariant     *value,
  *
  * The arguments that this function collects are determined by
  * scanning @format_string from start to end.  Brackets do not impact
- * the collection of arguments.  Each other character that is
- * encountered will result in an argument being collected.
+ * the collection of arguments (except when following 'a', 'm' or '@';
+ * see below).  Each other character that is encountered will result
+ * in an argument being collected.
  *
  * Arguments for the base types are expected as follows:
  * <informaltable>
@@ -819,10 +820,12 @@ g_variant_valist_get (GVariant     *value,
  * to a valid #GVariant instance.
  *
  * If an array type is encountered in @format_string, a
- * #GVariantBuilder is collected and has g_variant_builder_end()
+ * (#GVariantBuilder *) is collected and has g_variant_builder_end()
  * called on it.  The type of the array has no impact on argument
  * collection but is checked against the type of the array and can be
- * used to infer the type of an empty array.
+ * used to infer the type of an empty array.  As a special exception,
+ * if %NULL is given then an empty array of the given type will be
+ * used.
  *
  * If a maybe type is encountered in @format_string, then the expected
  * arguments vary depending on the type.
@@ -878,13 +881,18 @@ g_variant_valist_get (GVariant     *value,
  *   </tgroup>
  * </informaltable>
  *
- * If a '*' character is encountered in @format_string then a
- * (#GVariant *) is collected which must be non-%NULL and must point
- * to a valid #GVariant instance.  This #GVariant is inserted directly
- * at the given position.
+ * If a '@' character is encountered in @format_string, followed by a
+ * type string, then a (#GVariant *) is collected which must be
+ * non-%NULL and must point to a valid #GVariant instance.  This
+ * #GVariant is inserted directly at the given position.  The given
+ * #GVariant must match the provided format string.
+ *
+ * '*' means exactly the same as '@*'. 'r' means exactly the same as
+ * '@r'.  '?' means exactly the same as '@?'.
  *
  * The first character of the format string must not be '*' '?' '@' or
- * 'r'.
+ * 'r'; in essence, a new #GVariant must always be constructed by this
+ * function (and not merely passed through it unmodified).
  *
  * Please note that the syntax of the format string is very likely to
  * be extended in the future.
@@ -962,6 +970,184 @@ g_variant_new_va (gpointer      must_be_null,
   return value;
 }
 
+/**
+ * g_variant_get:
+ * @value: a #GVariant instance
+ * @format_string: a #GVariant format string
+ * @...: arguments, as per @format_string
+ *
+ * Deconstructs a #GVariant instance.
+ *
+ * Think of this function as an analogue to scanf().
+ *
+ * The arguments that are expected by this function are entirely
+ * determined by @format_string.  @format_string also restricts the
+ * permissible types of @value.  It is an error to give a value with
+ * an incompatible type.
+ *
+ * In the most simple case, @format_string is exactly equal to a
+ * concrete #GVariantType type string and @value must have that type.
+ * All exceptions to this case are explicitly mentioned below.
+ *
+ * The arguments that this function collects are determined by
+ * scanning @format_string from start to end.  Brackets do not impact
+ * the collection of arguments (except when following 'a', 'm' or '@';
+ * see below).  Each other character that is encountered will result
+ * in an argument being collected.
+ *
+ * All arguments are pointer types.  Any pointer may be %NULL and in
+ * that case, collection will be supressed for that position (ie: you
+ * can use a %NULL pointer if you don't care about the value of a
+ * particular child of a complex value).
+ *
+ * Arguments for the base types are expected as follows:
+ * <informaltable>
+ *   <tgroup cols='2'>
+ *     <colspec align='center'/>
+ *     <colspec align='center'/>
+ *     <thead>
+ *       <row>
+ *         <entry>Character</entry>
+ *         <entry>Argument Type</entry>
+ *       </row>
+ *     </thead>
+ *     <tbody>
+ *       <row>
+ *         <entry><literal>b</literal></entry>
+ *         <entry>#gboolean*</entry>
+ *       </row>
+ *       <row>
+ *         <entry><literal>y</literal></entry>
+ *         <entry>#guchar*</entry>
+ *       </row>
+ *       <row>
+ *         <entry><literal>n</literal></entry>
+ *         <entry>#gint16*</entry>
+ *       </row>
+ *       <row>
+ *         <entry><literal>q</literal></entry>
+ *         <entry>#guint16*</entry>
+ *       </row>
+ *       <row>
+ *         <entry><literal>i</literal></entry>
+ *         <entry>#gint32*</entry>
+ *       </row>
+ *       <row>
+ *         <entry><literal>u</literal></entry>
+ *         <entry>#guint32*</entry>
+ *       </row>
+ *       <row>
+ *         <entry><literal>x</literal></entry>
+ *         <entry>#gint64*</entry>
+ *       </row>
+ *       <row>
+ *         <entry><literal>t</literal></entry>
+ *         <entry>#guint64*</entry>
+ *       </row>
+ *       <row>
+ *         <entry><literal>d</literal></entry>
+ *         <entry>#gdouble*</entry>
+ *       </row>
+ *       <row>
+ *         <entry><literal>s</literal></entry>
+ *         <entry>const #gchar *</entry>
+ *       </row>
+ *       <row>
+ *         <entry><literal>o</literal></entry>
+ *         <entry>const #gchar *</entry>
+ *       </row>
+ *       <row>
+ *         <entry><literal>g</literal></entry>
+ *         <entry>const #gchar *</entry>
+ *       </row>
+ *     </tbody>
+ *   </tgroup>
+ * </informaltable>
+ *
+ * If a 'v' character is encountered in @format_string then a
+ * (#GVariant **) is collected.  If this is non-%NULL then it is set
+ * to a new reference to a #GVariant.  You must call g_variant_unref()
+ * on it later.
+ *
+ * If an array type is encountered in @format_string, a
+ * (#GVariantIter *) is collected.  If this is non-%NULL then the
+ * #GVariantIter at which it points will be initialised for iterating
+ * over the array.  The array must be iterated (or the iter cancelled)
+ * in order to avoid leaking memory.
+ *
+ * If a maybe type is encountered in @format_string, then the expected
+ * arguments vary depending on the type.
+ *
+ * <informaltable>
+ *   <tgroup cols='3'>
+ *     <colspec align='center'/>
+ *     <colspec align='center'/>
+ *     <colspec align='left'/>
+ *     <thead>
+ *       <row>
+ *       <entry>Format string</entry>
+ *       <entry>Argument Type</entry>
+ *       <entry>Notes</entry>
+ *       </row>
+ *     </thead>
+ *     <tbody>
+ *       <row>
+ *         <entry>ms</entry>
+ *         <entry>const #gchar *</entry>
+ *         <entry>set to %NULL in case of Nothing</entry>
+ *       </row>
+ *       <row>
+ *         <entry>mo</entry>
+ *         <entry>const #gchar *</entry>
+ *         <entry>set to %NULL in case of Nothing</entry>
+ *       </row>
+ *       <row>
+ *         <entry>mg</entry>
+ *         <entry>const #gchar *</entry>
+ *         <entry>set to %NULL in case of Nothing</entry>
+ *       </row>
+ *       <row>
+ *         <entry>mv</entry>
+ *         <entry>#GVariant *</entry>
+ *         <entry>set to %NULL in case of Nothing</entry>
+ *       </row>
+ *       <row>
+ *         <entry>m *</entry>
+ *         <entry>#GVariant *</entry>
+ *         <entry>set to %NULL in case of Nothing</entry>
+ *       </row>
+ *       <row>
+ *         <entry>otherwise</entry>
+ *         <entry>#gboolean*</entry>
+ *         <entry>
+ *           If %NULL is given then the entire value is ignored.
+ *           Else, the #gboolean is set to %TRUE to indicate that the
+ *           maybe is non-Nothing or %FALSE to indicate Nothing.  In
+ *           the %TRUE case, the normal arguments (as per the format
+ *           string) are collected and handled normally.  In the
+ *           %FALSE case, the normal arguments are collected and
+ *           ignored.  This allows the same set of arguments to be
+ *           given without knowing the content of the value ahead of
+ *           time.
+ *         </entry>
+ *       </row>
+ *     </tbody>
+ *   </tgroup>
+ * </informaltable>
+ *
+ * If a '@' character is encountered in @format_string, followed by a
+ * type string, then a (#GVariant **) is collected.  If this is
+ * non-%NULL then it is set to a new reference to a #GVariant the
+ * corresponds to the value at the current position.  You must call
+ * g_variant_unref() on it later.  The returned value will match the
+ * type string provided.
+ *
+ * '*' means exactly the same as '@*'. 'r' means exactly the same as
+ * '@r'.  '?' means exactly the same as '@?'.
+ *
+ * Please note that the syntax of the format string is very likely to
+ * be extended in the future.
+ **/
 void
 g_variant_get (GVariant    *value,
                const gchar *format_string,
diff --git a/glib/gvarianttype.c b/glib/gvarianttype.c
index b17d74a..8569aea 100644
--- a/glib/gvarianttype.c
+++ b/glib/gvarianttype.c
@@ -17,6 +17,15 @@
 #include "galias.h"
 
 /**
+ * SECTION: gvarianttype
+ * @title: GVariantType
+ * @short_description: a variant type system
+ * @see_also: GVariantType
+ *
+ * A #GVariantType represents the type of a #GVariant instance.
+ **/
+
+/**
  * GVariantType:
  *
  * An opaque type representing either the type of a #GVariant instance
@@ -61,7 +70,7 @@
  * Any type that has a type string that can be generated from 'type'
  * is in the class %G_VARIANT_TYPE_CLASS_ALL.  This is all types.
  *
- * Each type is a member of exactly one other #GVariantTypeClass.
+ * Each type is a member of at least one other #GVariantTypeClass.
  *
  * Note that, in reality, a #GVariantType is just a string pointer
  * cast to an opaque type.  It is only valid to have a pointer of
@@ -298,7 +307,8 @@ g_variant_type_peek_string (const GVariantType *type)
  * @returns: the corresponding type string (must be freed)
  *
  * Returns a newly-allocated copy of the type string corresponding to
- * @type.  The return result must be freed using g_free().
+ * @type.  The return result is nul-terminated and must be freed using
+ * g_free().
  **/
 gchar *
 g_variant_type_dup_string (const GVariantType *type)
@@ -580,9 +590,13 @@ g_variant_type_is_in_class (const GVariantType *type,
  *
  * Determines the smallest type class containing @type.
  *
- * For example, although %G_VARIANT_TYPE_CLASS_ALL matches all types,
- * it will never be returned by this function except for the type
- * %G_VARIANT_TYPE_ANY.
+ * For example, this function would return
+ * %G_VARIANT_TYPE_CLASS_BOOLEAN for %G_VARIANT_TYPE_BOOLEAN and
+ * %G_VARIANT_TYPE_CLASS_ARRAY for the type corresponding to the type
+ * string "ai".  %G_VARIANT_TYPE_CLASS_ALL is returned for
+ * %G_VARIANT_TYPE_ANY and for no other types (because although it
+ * contains all types, it is not the smallest containing class for any
+ * other type).
  **/
 GVariantTypeClass
 g_variant_type_get_class (const GVariantType *type)
diff --git a/glib/gvarianttype.h b/glib/gvarianttype.h
index cded623..8fe2ce0 100644
--- a/glib/gvarianttype.h
+++ b/glib/gvarianttype.h
@@ -176,10 +176,11 @@ typedef enum
  * The type of a DBus type signature.  These are strings of a specific
  * format used as type signatures for DBus methods and messages.
  *
- * Any valid #GVariantType signature string is a valid DBus type
- * signature.  In addition, a concatenation of any number of valid
- * #GVariantType  signature strings is also a valid DBus type
- * signature.
+ * Any valid concrete #GVariantType signature string is a valid DBus
+ * type signature.  In addition, a concatenation of any number of
+ * valid concrete #GVariantType signature strings is also a valid DBus
+ * type signature, subject to the restriction that DBus signature
+ * strings have a maximum length of 255 characters.
  **/
 #define G_VARIANT_TYPE_SIGNATURE            ((const GVariantType *) "g")
 
@@ -194,7 +195,8 @@ typedef enum
 /**
  * G_VARIANT_TYPE_UNIT:
  *
- * The empty structure type.  Has only one valid instance.
+ * The empty structure type.  Has only one instance.  Known also as
+ * "triv" or "void".
  **/
 #define G_VARIANT_TYPE_UNIT                 ((const GVariantType *) "()")
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]