[gxml] Improve GXml Vala bindings documentation
- From: Daniel Espinosa Ortiz <despinosa src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gxml] Improve GXml Vala bindings documentation
- Date: Tue, 30 Sep 2014 05:29:44 +0000 (UTC)
commit b766a11c2bfe83f9aae11f585fa1f0a47cbae34c
Author: Daniel Espinosa <esodan gmail com>
Date: Tue Sep 30 00:28:56 2014 -0500
Improve GXml Vala bindings documentation
configure.ac | 2 +-
docs/valadoc/Makefile.am | 2 +-
gxml/BackedNode.vala | 8 +-
gxml/Document.vala | 18 ---
gxml/DocumentType.vala | 2 +-
gxml/DomException.vala | 20 ++-
gxml/EntityReference.vala | 19 ++--
gxml/Enumeration.vala | 13 ++
gxml/NamedNodeMap.vala | 12 ++-
gxml/Node.vala | 13 +-
gxml/Serializable.vala | 239 +++++++++++++++++++++++------------
gxml/SerializableContainer.vala | 16 ++--
gxml/SerializableGeeArrayList.vala | 6 +
gxml/SerializableGeeDualKeyMap.vala | 5 +
gxml/SerializableGeeHashMap.vala | 7 +-
gxml/SerializableGeeTreeMap.vala | 7 +-
gxml/SerializableJson.vala | 15 +--
gxml/SerializableMapDualKey.vala | 15 ++-
gxml/SerializableMapKey.vala | 12 ++-
gxml/SerializableObjectModel.vala | 13 ++
20 files changed, 293 insertions(+), 151 deletions(-)
---
diff --git a/configure.ac b/configure.ac
index 25bdc2c..188dcc0 100644
--- a/configure.ac
+++ b/configure.ac
@@ -165,7 +165,7 @@ AC_ARG_ENABLE([devhelp-docs],
[enable_devhelp_docs=$enableval], [enable_devhelp_docs=no])
AC_ARG_ENABLE([gtk-docs],
AS_HELP_STRING([--enable-gtk-docs],[Enable gtk-doc documentation generation]),
- [enable_devhelp_docs=$enableval], [enable_gtk_docs=no])
+ [enable_gtk_docs=$enableval], [enable_gtk_docs=no])
dnl Find yelp-build program
enable_mallard_doc="no"
diff --git a/docs/valadoc/Makefile.am b/docs/valadoc/Makefile.am
index adf1a0f..6d81987 100644
--- a/docs/valadoc/Makefile.am
+++ b/docs/valadoc/Makefile.am
@@ -5,9 +5,9 @@ VALADOC_FLAGS = \
--force \
--package-name=gxml-$(API_VERSION) \
--package-version=$(PACKAGE_VERSION) \
- $(top_srcdir)/vapi/libxml-2.0.vapi \
--pkg glib-2.0 \
--pkg gio-2.0 \
+ --pkg libxml-2.0 \
--pkg gee-0.8 \
--vapidir=$(top_srcdir)/gxml \
--vapidir=$(top_srcdir)/vapi \
diff --git a/gxml/BackedNode.vala b/gxml/BackedNode.vala
index 985d48b..a880c60 100644
--- a/gxml/BackedNode.vala
+++ b/gxml/BackedNode.vala
@@ -1,4 +1,4 @@
-/* -*- Mode: vala; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */
+/* -*- Mode: vala; indent-tabs-mode: t; c-basic-offset: 2; tab-width: 2 -*- */
/* BackedNode.vala
*
* Copyright (C) 2011-2013 Richard Schwarting <aquarichy gmail com>
@@ -29,7 +29,7 @@ namespace GXml {
/**
* An internal class for nodes whose content is stored in a
* corresponding Xml.Node.
- *
+ *
* This would normally be hidden, but Vala wants base classes
* to be at least as public as subclasses.
*/
@@ -42,7 +42,7 @@ namespace GXml {
owner.node_dict.insert (node, this);
}
- /** Constructors */
+ /* Constructors */
internal BackedNode (Xml.Node *node, Document owner) {
base ((NodeType)node->type, owner);
@@ -86,7 +86,7 @@ namespace GXml {
}
}
/**
- * Add a new namespace to this { link GXml.Node}
+ * { inheritDoc}
*/
public override NamespaceAttr? add_namespace_attr (string uri, string prefix)
{
diff --git a/gxml/Document.vala b/gxml/Document.vala
index 3832b24..d33f912 100644
--- a/gxml/Document.vala
+++ b/gxml/Document.vala
@@ -23,24 +23,6 @@
*/
-/*
- * GXml
- * Copyright (C) Richard Schwarting <aquarichy gmail com> et al, 2011
- *
- * GXml is free software; you can redistribute it and/or modify it
- * under the terms of the GNU Lesser General Public License as
- * published by the Free Software Foundation; either version 2.1 of
- * the License, or (at your option) any later version.
- *
- * GXml is distributed in the hope that it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
- * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General
- * Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public
- * License along with GXml. If not, see <http://www.gnu.org/licenses/>.
- */
-
/* TODO:
* * later on, go over libxml2 docs for Tree and Node and Document, etc., and see if we're missing anything
significant
* * compare performance between libxml2 and GXml (should be a little different, but not too much)
diff --git a/gxml/DocumentType.vala b/gxml/DocumentType.vala
index 4a6a182..c42f971 100644
--- a/gxml/DocumentType.vala
+++ b/gxml/DocumentType.vala
@@ -26,7 +26,7 @@
namespace GXml {
/**
* Defines a Document, such as the entities that it can use.
- *
+ *
* For more, see: [[http://www.w3.org/TR/DOM-Level-1/level-one-core.html#ID-412266927]]
*/
public class DocumentType : Node {
diff --git a/gxml/DomException.vala b/gxml/DomException.vala
index ec707b2..e6fbe50 100644
--- a/gxml/DomException.vala
+++ b/gxml/DomException.vala
@@ -1,4 +1,4 @@
-/* -*- Mode: vala; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */
+/* -*- Mode: vala; indent-tabs-mode: t; c-basic-offset: 2; tab-width: 2 -*- */
/* DomException.vala
*
* Copyright (C) 2011-2013 Richard Schwarting <aquarichy gmail com>
@@ -25,6 +25,12 @@
namespace GXml {
public static DomException last_error = DomException.NONE;
+ /**
+ * Log DOM exception warnings.
+ *
+ * @param exception rised
+ * @param message message to log
+ */
public static void warning (GXml.DomException exception, string message) {
GXml.last_error = exception;
GLib.warning ("%s", message);
@@ -32,7 +38,7 @@ namespace GXml {
/**
* Describes various error states. For more, see
- *
+ *
* Version: DOM Level 1 Core<<BR>>
* URL: [[http://www.w3.org/TR/DOM-Level-1/level-one-core.html#ID-BBACDC08]]
*/
@@ -48,9 +54,10 @@ namespace GXml {
* An index or size is out of range, like less than 0 or exceeding some upper bound.
*/
INDEX_SIZE,
+ // TODO: figure out what the limits of strings are in vala
/**
* Text exceeds the maximum size supported in our string implementation.
- */ // TODO: figure out what the limits of strings are in vala
+ */
DOMSTRING_SIZE,
/**
* A node asked to be inserted into an invalid location.
@@ -60,9 +67,10 @@ namespace GXml {
* A node created for one document wanted to be used in another.
*/
WRONG_DOCUMENT,
+ // TODO: which characters are invalid?
/**
* An invalid character was found in a name.
- */ // TODO: which characters are invalid?
+ */
INVALID_CHARACTER,
/**
* Tried to specify data for a node that did not support it.
@@ -107,11 +115,9 @@ namespace GXml {
* URL: [[http://www.w3.org/TR/DOM-Level-3-Core/core.html#DOMException-NAMESPACE_ERR]]
*/
NAMESPACE,
-
+ //TODO: consider better naming for this
/**
* Non-DOM error
- *
- * TODO: consider better naming for this
*/
X_OTHER;
}
diff --git a/gxml/EntityReference.vala b/gxml/EntityReference.vala
index 5284323..49b77de 100644
--- a/gxml/EntityReference.vala
+++ b/gxml/EntityReference.vala
@@ -21,33 +21,32 @@
* Richard Schwarting <aquarichy gmail com>
* Daniel Espinosa <esodan gmail com>
*/
+/* TODO: do we need an EntityReference? find out what it's used for */
+// TODO: figure out some way to represent this from libxml2, or handle it ourselves
+// may not even need it while based on libxml2
+// It's possible that libxml2 already expands entity references and that this class
+// won't be used
+// TODO: make sure that character entity references (like the one used in the example above, are valid
namespace GXml {
- /* TODO: do we need an EntityReference? find out what it's used for */
- // TODO: figure out some way to represent this from libxml2, or handle it ourselves
- // may not even need it while based on libxml2
- // It's possible that libxml2 already expands entity references and that this class
- // won't be used
-
/**
* A reference to an unparsed { link GXml.Entity}, like "'" for an apostrophe.
- *
+ *
* To create one, use { link GXml.Document.create_entity_reference}.
- *
+ *
* The entity name, e.g. "apos", is stored as the EntityReference's `node_name`.
* For more, see: [[http://www.w3.org/TR/DOM-Level-1/level-one-core.html#ID-11C98490]]
*/
- // TODO: make sure that character entity references (like the one used in the example above, are valid
public class EntityReference : Node {
internal EntityReference (string refname, Document doc) {
// TODO: may want to handle refname differently
base (NodeType.ENTITY_REFERENCE, doc); // TODO: what should we pass up?
this.node_name = refname;
}
+ // TODO: not sure if that's correct
/**
* Stores the reference entity's name ("apos" for ').
*/
- // TODO: not sure if that's correct ^
public override string node_name {
get;
private set;
diff --git a/gxml/Enumeration.vala b/gxml/Enumeration.vala
index 1399b49..383a763 100644
--- a/gxml/Enumeration.vala
+++ b/gxml/Enumeration.vala
@@ -23,6 +23,19 @@
using GXml;
namespace GXml {
+ /**
+ * Convenient static methods for enumeration serialization to string.
+ *
+ * Enumerations have a set of utility methods to better represent on
+ * serialisation/deserialization.
+ *
+ * Enumerations could be converted to string using its definition on { link GLib.EnumClass},
+ * by taking its nick name directly or converting to its camel case representation.
+ *
+ * Any enumeration value type in a <code>GLib.Object</code>'s property could be
+ * deserialized from its definition given on { link GLib.EnumClass} (name and
+ * nick) or from its camel case representation.
+ */
public class Enumeration
{
/**
diff --git a/gxml/NamedNodeMap.vala b/gxml/NamedNodeMap.vala
index 2f2351d..d38f771 100644
--- a/gxml/NamedNodeMap.vala
+++ b/gxml/NamedNodeMap.vala
@@ -1,8 +1,8 @@
-/* -*- Mode: vala; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */
+/* -*- Mode: vala; indent-tabs-mode: t; c-basic-offset: 2; tab-width: 2 -*- */
/* Node.vala
*
* Copyright (C) 2011-2013 Richard Schwarting <aquarichy gmail com>
- * Copyright (C) 2011 Daniel Espinosa <esodan gmail com>
+ * Copyright (C) 2011,2014 Daniel Espinosa <esodan gmail com>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
@@ -25,6 +25,9 @@ using GXml;
using Gee;
namespace GXml {
+ /**
+ * A collection of elements with a named objects.
+ */
public interface NamedNodeMap<T> : GLib.Object {
// TODO: consider adding lookup, remove, etc from GLib.HashTable as convenience API
// TODO: figure out how to let people do attributes["pie"] for attributes.get_named_item
("pie"); GLib HashTables can do it
@@ -39,6 +42,11 @@ namespace GXml {
}
}
+ /**
+ * A class implementing { link NamedNodeMap} interface for { link Attr} objects.
+ *
+ * A collection of { link NamedNodeMap} of type { link Attr} objects in a { link Element}.
+ */
public class NamedAttrMap : GLib.Object, NamedNodeMap<Attr?> {
private Element elem;
diff --git a/gxml/Node.vala b/gxml/Node.vala
index 54aaa4b..8514597 100644
--- a/gxml/Node.vala
+++ b/gxml/Node.vala
@@ -35,7 +35,7 @@ namespace GXml {
* Version: DOM Level 1 Core<<BR>>
* URL: [[http://www.w3.org/TR/DOM-Level-1/level-one-core.html#ID-1950641247]]
*/
- public class Node : GLib.Object {
+ public abstract class Node : GLib.Object {
/* Constructors */
internal Node (NodeType type, Document owner) {
this.node_type = type;
@@ -95,12 +95,12 @@ namespace GXml {
/* Properties */
+ /* TODO: determine best API for exposing these, as it's not defined in the IDL */
/**
* The list of attributes that store namespace definitions. This is not part of a DOM spec.
*
* The caller must free this using { link GLib.Object.unref}.
*/
- /* @TODO: determine best API for exposing these, as it's not defined in the IDL */
public virtual NodeList? namespace_definitions {
get {
return null;
@@ -250,6 +250,10 @@ namespace GXml {
internal set {}
}
+
+ /*
+ * TODO: identify node types that use children for values, like attribute
+ */
/**
* List of child nodes to this node. These sometimes
* represent the value of a node as a tree of
@@ -268,9 +272,6 @@ namespace GXml {
* Version: DOM Level 1 Core<<BR>>
* URL: [[http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#ID-1451460987]]
*/
- /*
- * @todo: identify node types that use children for values, like attribute
- */
public virtual NodeList? child_nodes {
// TODO: need to implement NodeList
owned get { return null; }
@@ -497,6 +498,7 @@ namespace GXml {
return false;
}
+ // TODO: ask Colin Walters about storing docs in GIR files (might have not been him)
/**
* Provides a string representation of this node.
*
@@ -512,7 +514,6 @@ namespace GXml {
* @return XML string for node, which must be free
* this.
*/
- // TODO: ask Colin Walters about storing docs in GIR files (might have not been him)
public virtual string to_string (bool format = false, int level = 0) {
return "Node(%d:%s)".printf (this.node_type, this.node_name);
}
diff --git a/gxml/Serializable.vala b/gxml/Serializable.vala
index 0b68fc6..00b0f16 100644
--- a/gxml/Serializable.vala
+++ b/gxml/Serializable.vala
@@ -1,4 +1,4 @@
-/* -*- Mode: vala; indent-tabs-mode: nil; c-basic-offset: 3; tab-width: 3 -*- */
+/* -*- Mode: vala; indent-tabs-mode: nil; c-basic-offset: 2; tab-width: 2 -*- */
/* Serializable.vala
*
* Copyright (C) 2013 Daniel Espinosa <esodan gmail com>
@@ -22,47 +22,63 @@
namespace GXml {
/**
- * Interface allowing implementors direct control over serialisation of properties and other data
+ * GXml { link GLib.Object} serialization framework main interface to XML files.
+ *
+ * Implementors of this interface, could define or override the way you want to
+ * represent your class in a XML file.
*/
- public interface Serializable : GLib.Object {
- /**
- * Convenient property to store serializable properties
- */
- protected abstract ParamSpec[] properties { get; set; }
- /**
- * Store all properties to be ignored on serialization.
- *
- * Use property's cannonical name as key and its { link GLib.ParamSpec}. To
- * get the last one use { link GLib.Object.get_class} and use, again, property's
- * cannonical name to find it.
- *
- * Long named properties like this 'ignored_serializable_properties' are stored
- * by GObject using its cannonical name, then you must use it as key, in this
- * case use 'ignored-serializable-properties'.
- *
- * This property is ignored on serialisation.
- *
- * Implementors: By default { link list_serializable_properties} initialize
- * this property to store all public properties, except this one. Make shure to
- * call { link init_properties} before add new propeties.
- */
- public abstract HashTable<string,GLib.ParamSpec> ignored_serializable_properties { get; protected set; }
- /**
- * Return false if you want to ignore unknown properties and { link GXml.Node}'s
- * not in your class definition.
- *
- * Take care, disabling this feature you can lost data on serialization, because any unknown
- * property or element will be discarted.
- */
- public abstract bool get_enable_unknown_serializable_property ();
+ public interface Serializable : GLib.Object {
+ /**
+ * Convenient property to store serializable properties
+ */
+ protected abstract ParamSpec[] properties { get; set; }
+ /**
+ * Store all properties to be ignored on serialization.
+ *
+ * Use property's cannonical name as key and its { link GLib.ParamSpec}. To
+ * get the last one use { link GLib.Object.get_class} and use, again, property's
+ * cannonical name to find it.
+ *
+ * Long named properties like this 'ignored_serializable_properties' are stored
+ * by GObject using its cannonical name, then you must use it as key, in this
+ * case use 'ignored-serializable-properties'.
+ *
+ * This property is ignored on serialisation.
+ *
+ * Implementors: By default { link list_serializable_properties} initialize
+ * this property to store all public properties, except this one. Make shure to
+ * call { link init_properties} before add new propeties.
+ */
+ public abstract HashTable<string,GLib.ParamSpec> ignored_serializable_properties { get; protected set; }
+ /**
+ * Return false if you want to ignore unknown properties and { link GXml.Node}'s
+ * not in your class definition.
+ *
+ * Take care, disabling this feature you can lost data on serialization, because any unknown
+ * property or element will be discarted.
+ */
+ public abstract bool get_enable_unknown_serializable_property ();
/**
* On deserialization stores any { link GXml.Node} not used on this
* object, but exists in current XML file.
- *
+ *
* Node's name is used as key to find stored { link GXml.Node}.
- *
+ *
+ * XML allows great flexibility, providing different ways to represent the same
+ * information. This is a problem when you try to deserialize them.
+ *
+ * In order to deserialize correctly, you must create your XML, both by
+ * serializing a { link Serializable} object or by hand writing. By using the
+ * former, you can add extra information, like nodes or properties, but most of
+ * them could be ignored or lost on deserialization/serialization process. To
+ * avoid data lost, you can override { link get_enable_unknown_serializable_property}
+ * method in order to return true, your implementation or the ones in GXml, will
+ * store all unknown properties and nodes on deserialization and must serialize
+ * again back to the XML file. Even you are allowed to get this unknown objects
+ * by iterating on { link unknown_serializable_property} hash table.
+ *
* This property is ignored on serialisation.
- */
+ */
public abstract HashTable<string,GXml.Node> unknown_serializable_property { get; protected set; }
/**
@@ -79,49 +95,102 @@ namespace GXml {
* This property is ignored on serialisation.
*/
public abstract string? serialized_xml_node_value { get; protected set; default = null; }
- /**
- * Used to check { link GXml.Element}'s contents must be deseralized.
- *
- * By default no contents is serialized/deseralized. Implementors must implement
- * this function returning true in order to use { link serialized_xml_node_value}
- * property's value in serialization to set { link GXml.Element}'s contents.
- *
+ /**
+ * Used to check { link GXml.Element}'s contents must be deseralized.
+ *
+ * By default GXml's implementations doesn't deseriaze/serialize XML node contents.
+ * In order to enable it, you must override { link serialize_use_xml_node_value}
+ * method to return true and store XML node's content to { link serialized_xml_node_value}
+ * property.
+ *
+ * Implementors could set up methods to provide a clean easy to use API to set
+ * nodes contents. In most cases, users would like to set a value through a getter
+ * or setter or through a property in the class. If you use a property, you should
+ * add it to { link ignored_serializable_properties} in order to see its value
+ * in a XML node property.
+ *
*/
public abstract bool serialize_use_xml_node_value ();
- /**
- * Defines the way to set Node name.
- */
+ /**
+ * Defines the way to set Node name.
+ */
public abstract string node_name ();
- /**
- * Defines the way to set Node's property name, by using
- * it's nick instead of default name.
- */
+ /**
+ * Defines the way to set Node's property name, by using
+ * it's nick instead of default name.
+ *
+ * When serialize a class property, by default it uses its name given on class
+ * declaration, but is less common to see XML node properties with names like
+ * "your_property", but more common is to use "YourProperty". In order
+ * to use this kind of names, your implementation should use properties' nick
+ * name and override { link property_use_nick} method to return true. This should
+ * instruct your code to use this method to use property's nick name. This is
+ * the default in GXml default implementations.
+ */
public abstract bool property_use_nick ();
- /**
- * Serialize this object.
- *
- * This method must call serialize_property() recursivally on all properties
- * to serialize.
- *
- * @param node an { link GXml.Node} object to serialize to.
- */
+ /**
+ * Serialize this object.
+ *
+ * This method must call { link serialize_property} recursivally on all properties
+ * to serialize.
+ *
+ * { link Serializable} interface allows you to implement your own { link serialize}
+ * method. Your implementation should take a { link GXml.Node} and serialize
+ * over it. Given { link GXml.Node}, could be an { link GXml.Element} or a
+ * { link GXml.Document}, your implementaiton should take care about this and
+ * return XML nodes representing your class object.
+ *
+ * @param node an { link GXml.Node} object to serialize to.
+ */
public abstract GXml.Node? serialize (GXml.Node node) throws GLib.Error;
- /**
- * Serialize a property @prop on a { link GXml.Element}.
- *
- * This method is called recursivally by { link serialize} method over all properties
- * to be serialized.
+ /**
+ * Serialize a property @prop on a { link GXml.Element}.
+ *
+ * This method is called recursivally by { link serialize} method over all properties
+ * to be serialized.
+ *
+ * You can get control on class's properties to be serialized to XML. Allowing
+ * to provide ones, storing runtime information and ones to be stored in XML.
+ * By default, all object's properties are serialized. In order to skip properties
+ * from serialization process you must add its canonical name as key and its
+ * canonical name as value, to { link ignored_serializable_properties} store.
+ *
+ * Implementator must use { link ignored_serializable_properties} property to
+ * check if a property should be serialized. This allows to dynamically remove,
+ * on convenience, properties on serialization. You can use { link list_serializable_properties}
+ * method as a convenient function, using its default implementation, or even
+ * override it at your convenience to automate dynamic serializable properties
+ * at run time; just make sure to skip the unwanted properties.
+ *
+ * There are more methods to avoid properties serialization, like to override
+ * { link init_properties} default implementation. It stores all { link Serializable}'s
+ * properties to be ignored by default; you must ensure to initialize correctly,
+ * by calling { link default_init_properties} method before any other code in
+ * your overrided method.
+ *
*/
public abstract GXml.Node? serialize_property (GXml.Element element,
GLib.ParamSpec prop)
throws GLib.Error;
- /**
- * Deserialize this object.
- *
- * @param node { link GXml.Node} used to deserialize from.
- */
+ /**
+ * Deserialize this object.
+ *
+ * { link Serializable} interface allows you to implement your own { link deserialize}
+ * method. Your implementation should take a { link GXml.Node} and deserialize
+ * from it. Given { link GXml.Node}, could be an { link GXml.Element} or a
+ * { link GXml.Document}, your implementaiton should take care about this
+ * and return XML nodes representing your class object.
+ *
+ * Your implementation could take { link GXml.Element}'s name to detect the
+ * property to set up or detect the root element in a { link GXml.Document}
+ * to use. Then you can iterate over all node's properties and set up your
+ * object properties; you can use { link gvalue_to_string} to transform most
+ * common value types from string to the required value's type.
+ *
+ * @param node { link GXml.Node} used to deserialize from.
+ */
public abstract GXml.Node? deserialize (GXml.Node node)
throws GLib.Error;
/**
@@ -408,18 +477,26 @@ namespace GXml {
public abstract bool transform_from_string (string str, ref GLib.Value dest)
throws GLib.Error;
- /**
- * Transforms a string into another type hosted by { link GLib.Value}.
- *
- * A utility function that handles converting a string
- * representation of a value into the type specified by the
- * supplied #GValue dest. A #GXmlSerializableError will be
- * set if the string cannot be parsed into the desired type.
- *
- * @param str the string to transform into the given #GValue object
- * @param dest the #GValue out parameter that will contain the parsed value from the string
- * @return `true` if parsing succeeded, otherwise `false`
- */
+ /**
+ * Transforms a string into another type hosted by { link GLib.Value}.
+ *
+ * A utility function that handles converting a string
+ * representation of a value into the type specified by the
+ * supplied #GValue dest. A #GXmlSerializableError will be
+ * set if the string cannot be parsed into the desired type.
+ *
+ * { link Serializable} interface support a number of data types to convert
+ * from its string representation. These are supported types:
+ *
+ * a. integers: int8, int64, uint, long, ulong, char, uchar
+ * a. boolean
+ * a. floats: float, double
+ * a. enumerations
+ *
+ * @param str the string to transform into the given #GValue object
+ * @param dest the #GValue out parameter that will contain the parsed value from the string
+ * @return `true` if parsing succeeded, otherwise `false`
+ */
public static bool string_to_gvalue (string str, ref GLib.Value dest)
throws SerializableError
{
@@ -525,7 +602,7 @@ namespace GXml {
/**
* Transforms a { link GLib.Value} to its string representation.
*
- * By default use GObject standard transformations.
+ * By default use { link GLib.Value} standard transformations.
*
*/
public static string gvalue_to_string (GLib.Value val)
diff --git a/gxml/SerializableContainer.vala b/gxml/SerializableContainer.vala
index 187bf7e..a8b2656 100644
--- a/gxml/SerializableContainer.vala
+++ b/gxml/SerializableContainer.vala
@@ -20,24 +20,24 @@
* Daniel Espinosa <esodan gmail com>
*/
/**
- * Any {link GXml.Serializable} class having a collection managed list of {link GXml.Node} must implement
this
- * abstract class.
+ * Any { link GXml.Serializable} class having a collection managed list of
+ * { link GXml.Node} must implement this abstract class.
+ *
+ * Gee Serializable clases requires to be initialized with required typed objects to contain
+ * its collections and Serializable interface don't know required type. Then you must use this
+ * function to initialize any Serializable collection objects in order to serialize/deserialize
+ * all { link GXml.Node} to given clases.
*/
public abstract class GXml.SerializableContainer : SerializableObjectModel
{
/**
* Implementors must implement this function and initialize any Serializable container.
- *
- * Gee Serializable clases requires to be initialized with required typed objects to contain
- * its collections and Serializable interface don't know required type. Then you must use this
- * function to initialize any Serializable collection objects in order to serialize/deserialize
- * all {link GXml.Node} to given clases.
*/
public abstract void init_containers ();
}
/**
- * Fake interface to be implemented by any collection.
+ * Fake interface to be implemented by any collection of { link Serializable} objects.
*/
public interface GXml.SerializableCollection : Object, Serializable
{
diff --git a/gxml/SerializableGeeArrayList.vala b/gxml/SerializableGeeArrayList.vala
index b4fec6d..1df4bca 100644
--- a/gxml/SerializableGeeArrayList.vala
+++ b/gxml/SerializableGeeArrayList.vala
@@ -22,6 +22,12 @@
using GXml;
using Gee;
+/**
+ * A { link Serializable} objects container.
+ *
+ * It is derived It implements { link Serializable} and { link SerializableCollection}
+ * interfaces.
+ */
public class GXml.SerializableArrayList<G> : Gee.ArrayList<G>, Serializable, SerializableCollection
{
protected ParamSpec[] properties { get; set; }
diff --git a/gxml/SerializableGeeDualKeyMap.vala b/gxml/SerializableGeeDualKeyMap.vala
index 3db39f3..8667e81 100644
--- a/gxml/SerializableGeeDualKeyMap.vala
+++ b/gxml/SerializableGeeDualKeyMap.vala
@@ -22,6 +22,11 @@
using GXml;
using Gee;
+/**
+ * A { link Serializable} objects container. It uses two keys and value store.
+ *
+ * It implements { link Serializable} and { link SerializableCollection} interfaces.
+ */
public class GXml.SerializableDualKeyMap<P,S,V> : Object, Serializable, SerializableCollection
{
protected Gee.HashMultiMap<P,HashMap<S,V>> storage;
diff --git a/gxml/SerializableGeeHashMap.vala b/gxml/SerializableGeeHashMap.vala
index eb21231..9c70b98 100644
--- a/gxml/SerializableGeeHashMap.vala
+++ b/gxml/SerializableGeeHashMap.vala
@@ -20,7 +20,12 @@
* Daniel Espinosa <esodan gmail com>
*/
using GXml;
-
+/**
+ * A { link Serializable} objects container.
+ *
+ * It uses a key and value store implementing { link Gee.HashMap} interface.
+ * It implements { link Serializable} and { link SerializableCollection} interfaces.
+ */
public class GXml.SerializableHashMap<K,V> : Gee.HashMap<K,V>, Serializable, SerializableCollection
{
protected ParamSpec[] properties { get; set; }
diff --git a/gxml/SerializableGeeTreeMap.vala b/gxml/SerializableGeeTreeMap.vala
index fb8609e..901fb74 100644
--- a/gxml/SerializableGeeTreeMap.vala
+++ b/gxml/SerializableGeeTreeMap.vala
@@ -20,7 +20,12 @@
* Daniel Espinosa <esodan gmail com>
*/
using GXml;
-
+/**
+ * A { link Serializable} objects container.
+ *
+ * It uses a key and value store implementing { link Gee.TreeMap} interface.
+ * It implements { link Serializable} and { link SerializableCollection} interfaces.
+ */
public class GXml.SerializableTreeMap<K,V> : Gee.TreeMap<K,V>, Serializable, SerializableCollection
{
protected ParamSpec[] properties { get; set; }
diff --git a/gxml/SerializableJson.vala b/gxml/SerializableJson.vala
index 3c3ec6a..31f6f3a 100644
--- a/gxml/SerializableJson.vala
+++ b/gxml/SerializableJson.vala
@@ -50,14 +50,13 @@
/**
- * Serializes and deserializes { link GLib.Object}s to and from
- * { link GXml.Node}.
- *
- * Serialization can automatically serialize a variety of public
- * properties. { link GLib.Object}s can also implement the
- * { link GXml.Serializable} to partially or completely manage
- * serialization themselves, including non-public properties or
- * data types not automatically supported by { link GXml.Serialization}.
+ * An implementation of { link Serializable} using an { link Element} called "Object".
+ *
+ * { link Element} have two properties with object type and object id.
+ *
+ * It uses a set children { link Element} for each Object property with two { link Attr},
+ * one for its type and one for its name; property's value is set as the property
+ * { link Element}'s content text.
*/
public class GXml.SerializableJson : GLib.Object, GXml.Serializable
{
diff --git a/gxml/SerializableMapDualKey.vala b/gxml/SerializableMapDualKey.vala
index 5bfbf94..80e65ff 100644
--- a/gxml/SerializableMapDualKey.vala
+++ b/gxml/SerializableMapDualKey.vala
@@ -1,4 +1,4 @@
-/* -*- Mode: vala; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */
+/* -*- Mode: vala; indent-tabs-mode: nil; c-basic-offset: 2; tab-width: 2 -*- */
/* SerializableGeeTreeModel.vala
*
* Copyright (C) 2013 Daniel Espinosa <esodan gmail com>
@@ -20,8 +20,21 @@
* Daniel Espinosa <esodan gmail com>
*/
using GXml;
+/**
+ * Interface to get two keys used to store { link Serializable} objects.
+ *
+ * This interface must be implemented by classes derived from { link GXml.SerializableDualKeyMap}.
+ */
public interface GXml.SerializableMapDualKey<P,S> : Object
{
+ /**
+ * Implement this function to return the value to be used as primary key on
+ * { link SerializableDualKeyMap} containers.
+ */
public abstract P get_map_primary_key ();
+ /**
+ * Implement this function to return the value to be used as secondary key on
+ * { link SerializableDualKeyMap} containers.
+ */
public abstract S get_map_secondary_key ();
}
diff --git a/gxml/SerializableMapKey.vala b/gxml/SerializableMapKey.vala
index 944b1b0..592c471 100644
--- a/gxml/SerializableMapKey.vala
+++ b/gxml/SerializableMapKey.vala
@@ -1,4 +1,4 @@
-/* -*- Mode: vala; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */
+/* -*- Mode: vala; indent-tabs-mode: nil; c-basic-offset: 2; tab-width: 2 -*- */
/* SerializableGeeTreeModel.vala
*
* Copyright (C) 2013 Daniel Espinosa <esodan gmail com>
@@ -21,7 +21,17 @@
*/
using GXml;
+/**
+ * Interface to get one key used to store { link Serializable} objects.
+ *
+ * This interface must be implemented by classes derived from { link SerializableTreeMap}
+ * and { link SerializableHashMap}.
+ */
public interface GXml.SerializableMapKey<K> : Object
{
+ /**
+ * Implement this function to return the value to be used as key on { link SerializableTreeMap}
+ * and { link SerializableHashMap} containers.
+ */
public abstract K get_map_key ();
}
diff --git a/gxml/SerializableObjectModel.vala b/gxml/SerializableObjectModel.vala
index 96bba68..0160e8c 100644
--- a/gxml/SerializableObjectModel.vala
+++ b/gxml/SerializableObjectModel.vala
@@ -20,6 +20,19 @@
* Daniel Espinosa <esodan gmail com>
*/
+/**
+ * Object Model is an { link Serializable} implementation using { link Element}
+ * to represent { link GLib.Object} class objects.
+ *
+ * This implementation consider each object as a XML node, represented in GXml
+ * as a { link GXml.Element} and its properties is represented by { link GXml.Attr}.
+ * Each property, if it is a { link Serializable} object, is represented as child
+ * { link Element}.
+ *
+ * If a object's value property must be represented as a XML node content,
+ * then it requires to override { link Serializable.serialize_use_xml_node_value}
+ * and set value at { link Serializable.serialized_xml_node_value}.
+ */
public abstract class GXml.SerializableObjectModel : Object, Serializable
{
/* Serializable interface properties */
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
