diff options
author | Murray Cumming <murrayc@murrayc.com> | 2011-03-24 10:04:42 +0100 |
---|---|---|
committer | Murray Cumming <murrayc@murrayc.com> | 2011-03-24 10:04:42 +0100 |
commit | 2df20ecd72a90a5b961cbaad3d561a59b4f77307 (patch) | |
tree | 0ada0a1da7aa57c55662dbaf69cd69af7d19eca7 | |
parent | bc28ff1457c15eaebc8b1c7b1a078ac66d94b420 (diff) | |
download | glibmm-2df20ecd72a90a5b961cbaad3d561a59b4f77307.tar.gz |
Variant: Improved the documentation, based on the C documentation.
* glib/src/variant.hg: Also changed two methods to take std::string by
const &.
-rw-r--r-- | ChangeLog | 7 | ||||
-rw-r--r-- | glib/src/variant.hg | 81 |
2 files changed, 68 insertions, 20 deletions
@@ -1,5 +1,12 @@ 2011-03-24 Murray Cumming <murrayc@murrayc.com> + Variant: Improved the documentation, based on the C documentation. + + * glib/src/variant.hg: Also changed two methods to take std::string by + const &. + +2011-03-24 Murray Cumming <murrayc@murrayc.com> + Avoid a tarball dependency on mm-common. * configure.ac: Add a call to MM_CONFIG_DOCTOOL_DIR() telling it to diff --git a/glib/src/variant.hg b/glib/src/variant.hg index 235205ae..bccfda14 100644 --- a/glib/src/variant.hg +++ b/glib/src/variant.hg @@ -30,22 +30,52 @@ _DEFS(glibmm,glib) namespace Glib { -//TODO: Write C++ versions of the documentation. - /** @defgroup Variant Variant Data Types * - * Variant<> are specialized classes that deal with strongly typed - * variant data. They are used to wrap glib's GVariant API. For more - * information see the <a - * href="http://library.gnome.org/devel/glib/stable/glib-GVariant.html">glib - * variant - * API</a>. + * The Variant classes deal with strongly typed + * variant data. A Variant stores a value along with + * information about the type of that value. The range of possible + * values is determined by the type. The type system used is VariantType. + * + * See the VariantBase class and it's derived types, such as VariantContainerbase, + * and the Variant<> template type. + * + * Variant instances always have a type and a value (which are given + * at construction time). The type and value of a Variant + * can never change other than by the Variant itself being + * destroyed. A Variant cannot contain a pointer. + * + * Variant is heavily optimised for dealing with data in serialised + * form. It works particularly well with data located in memory-mapped + * files. It can perform nearly all deserialisation operations in a + * small constant time, usually touching only a single memory page. + * Serialised Variant data can also be sent over the network. + * + * Variant is largely compatible with D-Bus. Almost all types of + * #GVariant instances can be sent over D-Bus. See VariantType for + * exceptions. + * + * There is a Python-inspired text language for describing Variant + * values. Variant includes a printer for this language and a parser + * with type inferencing.</a>. */ //TODO: VariantBase class can be copied, so suggest how it can be dynamic casted to //derived types: See https://bugzilla.gnome.org/show_bug.cgi?id=644146 -/** The base class used to wrap glib's GVariant API. +//TODO: Add this documentation from the API if we are confident of it for the C++ wrapper: +// #GVariant is completely threadsafe. A #GVariant instance can be +// concurrently accessed in any way from any number of threads without +// problems. +// Note that we don't copy GVariant's documentation about Memory Use because +// it seems easy to get out of sync and people can look at that C documentation if necessary. + +/** This is the base class for all Variant types. + * + * If the actual type is known at compile-time then you should use a specific + * Variant<>, such as Variant<int>. Otherwise, you may use get_type(), + * is_of_type(), or cast_dynamic(). + * * @newin{2,28} * @ingroup Variant */ @@ -127,9 +157,18 @@ public: void byteswap(VariantBase& result) const; _IGNORE(g_variant_byteswap) + /** Cast to a specific variant type. + * For instance: + * @code + * Variant<std::string> derived = VariantBase::cast_dynamic< Variant<std::string> >(base); + * @endcode + * + * @param v The variant to cast to a specific type. + * @result The variant as a specific type. + * @throws std::bad_cast if the Variant was not of the expected type. + */ template<class V_CastTo> - static V_CastTo cast_dynamic(const VariantBase& v) - throw(std::bad_cast); + static V_CastTo cast_dynamic(const VariantBase& v) throw(std::bad_cast); }; @@ -181,8 +220,8 @@ public: : VariantBase(castitem, take_a_reference) {} - /** Creates a DBus object path variant with the contents of @a string. @a - * string must be a valid DBus object path. Use is_object_path() if unsure. + /** Creates a D-Bus object path variant with the contents of @a string. @a + * string must be a valid D-Bus object path. Use is_object_path() if unsure. * * @param output A location in which to store the new object path variant * instance. @@ -192,23 +231,25 @@ public: static void create_object_path(VariantStringBase& output, const std::string& object_path); - _WRAP_METHOD(static bool is_object_path(std::string string), g_variant_is_object_path) + _WRAP_METHOD(static bool is_object_path(const std::string& string), g_variant_is_object_path) - /** Creates a DBus type signature variant with the contents of @a string. @a - * string must be a valid DBus type signature. Use is_signature() if unsure. + /** Creates a D-Bus type signature variant with the contents of @a string. @a + * string must be a valid D-Bus type signature. Use is_signature() if unsure. * * @param output A location in which to store the new signature variant * instance. * @param signature A normal nul-terminated string. * @newin{2,28} */ - static void create_signature(VariantStringBase& output, - const std::string& object_path); + static void create_signature(VariantStringBase& output, + const std::string& object_path); - _WRAP_METHOD(static bool is_signature(std::string string), g_variant_is_signature) + _WRAP_METHOD(static bool is_signature(const std::string& string), g_variant_is_signature) }; -/** The base class from which variant containers derive. +/** The base class from which multiple-item Variants derive, such as Variants + * containing tuples or arrays. + * * @newin{2,28} * @ingroup Variant */ |