[json-glib] docs: Add long descriptions
- From: Emmanuele Bassi <ebassi src gnome org>
- To: svn-commits-list gnome org
- Cc:
- Subject: [json-glib] docs: Add long descriptions
- Date: Wed, 28 Oct 2009 12:02:28 +0000 (UTC)
commit fc0607c740b153acc96e4df12a12b042e08e831b
Author: Emmanuele Bassi <ebassi linux intel com>
Date: Wed Oct 28 12:01:21 2009 +0000
docs: Add long descriptions
The json-boxed and json-serializable sections are missing the
long description for the API reference.
json-glib/json-gboxed.c | 49 +++++++++++++++++++++++++++++++++++++---
json-glib/json-serializable.c | 5 +++-
2 files changed, 49 insertions(+), 5 deletions(-)
---
diff --git a/json-glib/json-gboxed.c b/json-glib/json-gboxed.c
index 09129c2..fa1f9a3 100644
--- a/json-glib/json-gboxed.c
+++ b/json-glib/json-gboxed.c
@@ -23,8 +23,46 @@
* SECTION:json-gboxed
* @short_description: Serialize and deserialize GBoxed types
*
- * FIXME
+ * GLib's #GBoxed type is a generic wrapper for arbitrary C structures.
*
+ * JSON-GLib allows serialization and deserialization of a #GBoxed type
+ * by registering functions mapping a #JsonNodeType to a specific
+ * #GType.
+ *
+ * When registering a #GBoxed type you should also register the
+ * corresponding transformation functions, e.g.:
+ *
+ * |[
+ * GType
+ * my_struct_get_type (void)
+ * {
+ * static GType boxed_type = 0;
+ *
+ * if (boxed_type == 0)
+ * {
+ * boxed_type =
+ * g_boxed_type_register_static (g_intern_static_string ("MyStruct"),
+ * (GBoxedCopyFunc) my_struct_copy,
+ * (GBoxedFreeFunc) my_struct_free);
+ *
+ * json_boxed_register_transform_func (boxed_type, JSON_NODE_OBJECT,
+ * my_struct_serialize,
+ * my_struct_deserialize);
+ * }
+ *
+ * return boxed_type;
+ * }
+ * ]|
+ *
+ * The serialization function will be invoked by json_boxed_serialize():
+ * it will be passed a pointer to the C structure and it must return a
+ * #JsonNode. The deserialization function will be invoked by
+ * json_boxed_deserialize(): it will be passed a #JsonNode and it must
+ * return a newly allocated C structure.
+ *
+ * It is possible to check whether a #GBoxed type can be deserialized
+ * from a specific #JsonNodeType, and whether a #GBoxed can be serialized
+ * and to which specific #JsonNodeType.
*/
#ifdef HAVE_CONFIG_H
@@ -153,12 +191,15 @@ json_boxed_register_transform_func (GType gboxed_type,
* json_boxed_can_serialize:
* @gboxed_type: a boxed type
* @node_type: (out): the #JsonNode type to which the boxed type can be
- * deserialized into
+ * serialized into
*
* Checks whether it is possible to serialize a #GBoxed of
- * type @gboxed_type into a #JsonNode of type @node_type
+ * type @gboxed_type into a #JsonNode. The type of the
+ * #JsonNode is placed inside @node_type if the function
+ * returns %TRUE and it's undefined otherwise.
*
- * Return value: %TRUE if the type can be serialized, %FALSE otherwise
+ * Return value: %TRUE if the type can be serialized,
+ * and %FALSE otherwise.
*
* Since: 0.10
*/
diff --git a/json-glib/json-serializable.c b/json-glib/json-serializable.c
index 277677b..1f596e1 100644
--- a/json-glib/json-serializable.c
+++ b/json-glib/json-serializable.c
@@ -21,7 +21,10 @@
* SECTION:json-serializable
* @short_description: Interface for serialize and deserialize special GObjects
*
- * FIXME
+ * #JsonSerializable is an interface for #GObject classes that
+ * allows controlling how the class is going to be serialized
+ * or deserialized by json_construct_gobject() and
+ * json_serialize_gobject() respectively.
*/
#ifdef HAVE_CONFIG_H
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]