GNOME.org
 

[glibmm] Variant[Iter,Type]: Add class docs.

commit 3b1a6acc6a941fde9dd76189dbeae4ee9b7d4205
Author: José Alburquerque <jaalburqu svn gnome org>
Date:   Wed Dec 15 18:13:03 2010 -0500

    	Variant[Iter,Type]: Add class docs.
    
    	* glib/src/variantiter.hg:
    	* glib/src/varianttype.hg: Add class docs.
    	* glib/src/keyfile.hg:
    	* glib/src/optiongroup.hg: Correct @newin{}s from 2,26 to 2,28.
    	* glib/src/variant.hg (VariantBase): Move the get_n_children() method
    	to Variant<VariantBase> since all containers essentially are created
    	in the C API as a GVariant containing one (or more) GVariant(s).  The
    	C++ container types (such as arrays, etc.) can derive from
    	Glib::Variant<VariantBase> to inherit the get_n_children() method.
    
    	* gio/src/gio_extra_objects.defs: Add GDBusProxy.

 ChangeLog                      |   16 +++++++++++
 gio/src/gio_extra_objects.defs |   26 +++++++++++++----
 glib/src/keyfile.hg            |    4 +-
 glib/src/optiongroup.hg        |    2 +-
 glib/src/variant.hg            |   19 +++++++-----
 glib/src/variantiter.hg        |    4 ++-
 glib/src/varianttype.hg        |   59 ++++++++++++++++++++++++++++++++++++++-
 7 files changed, 110 insertions(+), 20 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index ac9f4d1..0726341 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,19 @@
+2010-12-15  José Alburquerque  <jaalburqu svn gnome org>
+
+	Variant[Iter,Type]: Add class docs.
+
+	* glib/src/variantiter.hg:
+	* glib/src/varianttype.hg: Add class docs.
+	* glib/src/keyfile.hg:
+	* glib/src/optiongroup.hg: Correct @newin{}s from 2,26 to 2,28.
+	* glib/src/variant.hg (VariantBase): Move the get_n_children() method
+	to Variant<VariantBase> since all containers essentially are created
+	in the C API as a GVariant containing one (or more) GVariant(s).  The
+	C++ container types (such as arrays, etc.) can derive from
+	Glib::Variant<VariantBase> to inherit the get_n_children() method.
+
+	* gio/src/gio_extra_objects.defs: Add GDBusProxy.
+
 2010-12-15  Murray Cumming  <murrayc murrayc com>
 
 	Tell the documentation generator about MatchInfo.
diff --git a/gio/src/gio_extra_objects.defs b/gio/src/gio_extra_objects.defs
index b60825b..b3bbbc0 100644
--- a/gio/src/gio_extra_objects.defs
+++ b/gio/src/gio_extra_objects.defs
@@ -39,6 +39,26 @@
   (gtype-id "G_TYPE_DBUS_METHOD_INVOCATION")
 )
 
+; This helps DocParser.pm, which can't always guess how to break the "DB" part.
+(define-object DbusMethodInvocation
+  (in-module "GLib")
+  (c-name "GDBusMethodInvocation")
+  (gtype-id "G_TYPE_DBUS_METHOD_INVOCATION")
+)
+
+(define-object DBusProxy
+  (in-module "GLib")
+  (c-name "GDBusProxy")
+  (gtype-id "G_TYPE_DBUS_PROXY")
+)
+
+; This helps DocParser.pm, which can't always guess how to break the "DB" part.
+(define-object DbusProxy
+  (in-module "GLib")
+  (c-name "GDbusProxy")
+  (gtype-id "G_TYPE_DBUS_PROXY")
+)
+
 (define-object DBusServer
   (in-module "GLib")
   (c-name "GDBusServer")
@@ -52,12 +72,6 @@
   (gtype-id "G_TYPE_DBUS_SERVER")
 )
 
-(define-object DBusMethodInvocation
-  (in-module "GLib")
-  (c-name "GDBusMethodInvocation")
-  (gtype-id "G_TYPE_DBUS_METHOD_INVOCATION")
-)
-
 (define-object DesktopAppInfo
   (in-module "GLib")
   (c-name "GDesktopAppInfo")
diff --git a/glib/src/keyfile.hg b/glib/src/keyfile.hg
index ae797b2..4796b24 100644
--- a/glib/src/keyfile.hg
+++ b/glib/src/keyfile.hg
@@ -217,7 +217,7 @@ public:
    * @return The value of @a key as a signed 64-bit integer, or <tt>0</tt> if
    * the key was not found or could not be parsed.
    * @throw Glib::KeyFileError.
-   * @newin{2,26}
+   * @newin{2,28}
    */
   gint64 get_int64(const Glib::ustring& key) const;
 
@@ -230,7 +230,7 @@ public:
    * @return The value of @a key as an unsigned 64-bit integer, or <tt>0</tt>
    * if the key was not found or could not be parsed.
    * @throw Glib::KeyFileError.
-   * @newin{2,26}
+   * @newin{2,28}
    */
   guint64 get_uint64(const Glib::ustring& key) const;
 
diff --git a/glib/src/optiongroup.hg b/glib/src/optiongroup.hg
index b1b2c5d..ce08b94 100644
--- a/glib/src/optiongroup.hg
+++ b/glib/src/optiongroup.hg
@@ -91,7 +91,7 @@ public:
    *
    * @param slot the slot to be used for translation.
    *
-   * @newin{2,26}
+   * @newin{2,28}
    */
   void set_translate_func(const SlotTranslate& slot);
   _IGNORE(g_option_group_set_translate_func)
diff --git a/glib/src/variant.hg b/glib/src/variant.hg
index 82decd2..2535d54 100644
--- a/glib/src/variant.hg
+++ b/glib/src/variant.hg
@@ -35,7 +35,7 @@ namespace Glib
  */
 
 /** The base class used to wrap glib's GVariant API.
- * @newin{2,26}
+ * @newin{2,28}
  * @ingroup glibmmVariant
  */
 class VariantBase
@@ -63,9 +63,6 @@ public:
   bool get_maybe(Glib::VariantBase& maybe) const;
   _IGNORE(g_variant_get_maybe)
 
-  //TODO: Somehow put this method only in specializations that use container types?:
-  _WRAP_METHOD(gsize get_n_children() const, g_variant_n_children)
-
   _WRAP_METHOD(gsize get_size() const, g_variant_get_size)
   _WRAP_METHOD(gconstpointer get_data(), g_variant_get_data)
   _WRAP_METHOD(void store(gpointer data) const, g_variant_store)
@@ -121,8 +118,8 @@ public:
    _IGNORE(g_variant_byteswap)
 };
 
-/** Template class from which other Glib::Variant<> specializations derive.
- * @newin{2,26}
+/** Template class used for the specialization of the Glib::Variant<> classes.
+ * @newin{2,28}
  * @ingroup glibmmVariant
  */
 template <class T>
@@ -140,12 +137,16 @@ _IGNORE(g_variant_get_type)
 /****************** Specializations ***********************************/
 
 /** Specialization of Glib::Variant containing a Glib::VariantBase.
- * @newin{2,26}
+ * @newin{2,28}
  * @ingroup glibmmVariant
  */
 template <>
 class Variant<VariantBase> : public VariantBase
 {
+  // Trick gmmproc into thinking this is derived from GVariant to wrap a method
+  // below.
+  _CLASS_GENERIC(Variant<VariantBase>, GVariant)
+
 public:
   typedef GVariant* CType;
 
@@ -165,10 +166,12 @@ public:
 
   VariantBase get() const;
   _IGNORE(g_variant_get_variant)
+
+  _WRAP_METHOD(gsize get_n_children() const, g_variant_n_children)
 };
 
 /** Specialization of Glib::Variant containing a Glib::ustring.
- * @newin{2,26}
+ * @newin{2,28}
  * @ingroup glibmmVariant
  */
 template <>
diff --git a/glib/src/variantiter.hg b/glib/src/variantiter.hg
index bbd1a2a..8ea6dac 100644
--- a/glib/src/variantiter.hg
+++ b/glib/src/variantiter.hg
@@ -25,7 +25,9 @@ namespace Glib
 //This can't be like a real iterator (like Gtk::TextIter),
 //because g_iter_value_get_next_value() both gets a value and changes the iterator.
 //GtkTextIter allows us to go forward and then separately get the current value.
-/** TODO: Documentation.
+/** VariantIter - An opaque data structure used to iterate through
+ * Glib::VariantBase containers such as arrays.
+ * @newin{2,28}
  */
 class VariantIter
 {
diff --git a/glib/src/varianttype.hg b/glib/src/varianttype.hg
index c034677..b4b4602 100644
--- a/glib/src/varianttype.hg
+++ b/glib/src/varianttype.hg
@@ -28,8 +28,63 @@ typedef struct _GVariantType GVariantType;
 namespace Glib
 {
 
-/** TODO
- * @newin{2,26}
+/** VariantType - The Glib::VariantBase type system.
+ * The Glib::VariantBase type system is based, in large part, on the DBus type
+ * system, with two major changes and some minor lifting of restrictions. <a
+ * href="http://dbus.freedesktop.org/doc/dbus-specification.html";>The
+ * DBus specification</a>, therefore, provides a significant amount of
+ * information that is useful when working with Glib::VariantBase.
+ *
+ * The first major change with respect to the DBus type system is the
+ * introduction of maybe (or "nullable") types. Any type in Glib::VariantBase
+ * can be converted to a maybe type, in which case, "nothing" (or "null")
+ * becomes a valid value. Maybe types have been added by introducing the
+ * character "m" to type strings.
+ *
+ * The second major change is that the Glib::VariantBase type system supports
+ * the concept of "indefinite types" -- types that are less specific than the
+ * normal types found in DBus. For example, it is possible to speak of "an
+ * array of any type" in Glib::VariantBase, where the DBus type system would
+ * require you to speak of "an array of integers" or "an array of strings".
+ * Indefinite types have been added by introducing the characters "*", "?" and
+ * "r" to type strings.
+ *
+ * Finally, all arbitrary restrictions relating to the complexity of types are
+ * lifted along with the restriction that dictionary entries may only appear
+ * nested inside of arrays.
+ *
+ * Just as in DBus, Glib::VariantBase types are described with strings ("type
+ * strings"). Subject to the differences mentioned above, these strings are of
+ * the same form as those found in DBus. Note, however: DBus always works in
+ * terms of messages and therefore individual type strings appear nowhere in
+ * its interface. Instead, "signatures" are a concatenation of the strings of
+ * the type of each argument in a message. Glib::VariantBase deals with single
+ * values directly so Glib::VariantBase type strings always describe the type
+ * of exactly one value. This means that a DBus signature string is generally
+ * not a valid Glib::VariantBase type string -- except in the case that it is
+ * the signature of a message containing exactly one argument.
+ *
+ * An indefinite type is similar in spirit to what may be called an abstract
+ * type in other type systems. No value can exist that has an indefinite type
+ * as its type, but values can exist that have types that are subtypes of
+ * indefinite types. That is to say, Glib::VariantBase::get_type() will never
+ * return an indefinite type, but calling Glib::VariantBase::is_of_type() with
+ * an indefinite type may return <tt>true</tt>. For example, you can not have a
+ * value that represents "an array of no particular type", but you can have an
+ * "array of integers" which certainly matches the type of "an array of no
+ * particular type", since "array of integers" is a subtype of "array of no
+ * particular type".
+ *
+ * This is similar to how instances of abstract classes may not directly exist
+ * in other type systems, but instances of their non-abstract subtypes may. For
+ * example, in gtkmm, no object that has the type of Gtk::Bin can exist (since
+ * Gtk::Bin is an abstract class), but a Gtk::Window can certainly be
+ * instantiated, and you would say that the Gtk::Window is a Gtk::Bin (since
+ * Gtk::Window is a subclass of Gtk::Bin).
+ *
+ * For a detailed description of the Glib::VariantBase type strings see the C
+ * API docs of GVariantType.
+ * @newin{2,28}
  * @ingroup glibmmVariant
  */
 class VariantType
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]