[gxml] Documentation improvements for GXml.Node and derived interfaces

[Daniel Espinosa Ortiz <despinosa src gnome org>]

commit f0e6dcfd1ed3a3d708d9baaf2f202d0590b6eeef
Author: Daniel Espinosa <esodan gmail com>
Date:   Mon May 4 10:38:50 2015 -0500

    Documentation improvements for GXml.Node and derived interfaces

 gxml/Attribute.vala |   10 ++++++++-
 gxml/Document.vala  |   23 +++++++++++++++++--
 gxml/Element.vala   |   21 +++++++++++++++++-
 gxml/Namespace.vala |   18 ++++++++++++++++
 gxml/Node.vala      |   57 +++++++++++++++++++++++++++++++++++++++++++++++++++
 5 files changed, 124 insertions(+), 5 deletions(-)
---
diff --git a/gxml/Attribute.vala b/gxml/Attribute.vala
index dd93abc..1bf1d9a 100644
--- a/gxml/Attribute.vala
+++ b/gxml/Attribute.vala
@@ -21,6 +21,14 @@
  */
 
 using Gee;
-
+/**
+ * Interface to handle XML tags properties.
+ *
+ * Its features relays on { link GXml.Node} interface inplementation to access
+ * { link GXml.Element} properties.
+ * 
+ * Attribute's name could be get from { link GXml.Node.name} property. Its value
+ * should be get from { link GXml.Node.value} property.
+ */
 public interface GXml.Attribute : Object, GXml.Node {}
 
diff --git a/gxml/Document.vala b/gxml/Document.vala
index 0aad66b..2de0f46 100644
--- a/gxml/Document.vala
+++ b/gxml/Document.vala
@@ -21,16 +21,33 @@
  */
 
 using Gee;
-
+/**
+ * Interface to handle XML documents.
+ *
+ * Provides basic interfaces to read and create XML documents.
+ */
 public interface GXml.Document : Object, GXml.Node
 {
+  /**
+   * XML document root node as a { link GXml.Element}.
+   */
   public abstract GXml.Node root { get; }
+  /**
+   * Stores a { link GLib.File} to save/read XML documents to/from.
+   */
   public abstract GLib.File file { get; set; }
   /**
-   * This method sould create a new { link GXml.Element}
-   * is a matter of you to add as a child to any other
+   * This method should create a new { link GXml.Element}.
+   * 
+   * Is a matter of you to add as a child to any other
    * { link GXml.Node}.
    */
   public abstract GXml.Node create_element (string name);
+  /**
+   * Creates a new { link GXml.Text}.
+   * 
+   * Is a matter of you to add as a child to any other
+   * { link GXml.Node}, like a { link GXml.Element} node.
+   */
   public abstract GXml.Node create_text (string text);
 }
diff --git a/gxml/Element.vala b/gxml/Element.vala
index af7b1b2..45a3e04 100644
--- a/gxml/Element.vala
+++ b/gxml/Element.vala
@@ -21,11 +21,30 @@
  */
 
 using Gee;
-
+/**
+ * Interface to access XML document's tags, properties and content.
+ * 
+ * Provides methods to create new XML tags properties and its values, and 
+ * access to tag's contents.
+ */
 public interface GXml.Element : Object, GXml.Node
 {
+    /**
+     * This merges all adjacent { link GXml.Text} nodes that are
+                * descendants of this { link GXml.Element}.
+      */
     public abstract void normalize ();
+    /**
+     * Add a new { link GXml.Attribute} to this { link GXml.Element}.
+     * 
+     * You should provide a name and a value.
+     */
     public abstract void set_attr (string name, string value);
+    /**
+     * Search for a { link GXml.Attribute} with given name.
+     * 
+     * All attributes could be get using { link GXml.Node.attrs} property.
+     */
     public abstract GXml.Node get_attr (string name);
     /**
      * This should be just a different name for { link GXml.Node.name}.
diff --git a/gxml/Namespace.vala b/gxml/Namespace.vala
index 6eeadcb..8caa3f1 100644
--- a/gxml/Namespace.vala
+++ b/gxml/Namespace.vala
@@ -22,9 +22,27 @@
 
 using Gee;
 
+/**
+ * Interface to handle XML Namespaces.
+ * 
+ * Basic information for a XML document's namespaces and applied to a given
+ * { link GXml.Node}.
+ * 
+ * Namespace management is a matter of this or other libraries, implementing
+ * this interfaces.
+ */
 public interface GXml.Namespace : Object
 {
+  /**
+   * Read-only property to get namespace's URI.
+   */
   public abstract string uri { get; }
+  /**
+   * Read-only property to get namespace's prefix.
+   * 
+   * Prefix should be added to { link GXml.Element} or { link GXml.Attribute}
+   * name in order to apply a given namespace, unless it is the default.
+   */
   public abstract string prefix { get; }
 }
 
diff --git a/gxml/Node.vala b/gxml/Node.vala
index 9abfac1..9ed99b9 100644
--- a/gxml/Node.vala
+++ b/gxml/Node.vala
@@ -22,19 +22,76 @@
 
 using Gee;
 
+/**
+ * Base interface providing basic functionalities to all GXml interfaces.
+ */
 public interface GXml.Node : Object
 {
+  /**
+   * Collection of Namespaces applied to this { link GXml.Node}.
+   */
   public abstract Gee.List<GXml.Namespace> namespaces { get; }
+  /**
+   * Collection of { link GXml.Node} as childs.
+   * 
+   * Depend on { link GXml.Node} type, this childs could of different, like,
+   * elements, element's contents or properties.
+   */
   public abstract Gee.BidirList<GXml.Node> childs { get; }
+  /**
+   * Attributes in this { link GXml.Node}.
+   */
   public abstract Gee.Map<string,GXml.Node> attrs { get; }
+  /**
+   * Node's name. The meaning differs, depending on node's type.
+   */
   public abstract string name { get; }
+  /**
+   * Node's value. The meaning differs, depending on node's type.
+   */
   public abstract string @value { get; set; }
+  /**
+   * Node's type as a enumeration.
+   */
   public abstract GXml.NodeType type_node { get; }
+  /**
+   * Node's XML document holding this node.
+   */
   public abstract GXml.Document document { get; }
+  /**
+   * Node's string representation.
+   */
   public abstract string to_string ();
+  /**
+   * Set a namespace to this node.
+   * 
+   * Search for existing document's namespaces and applies it if found or creates
+   * a new one, appending to document's namespaces collection.
+   */
   public abstract bool set_namespace (string uri, string prefix);
+  /**
+   * Node's defaults namespace's prefix.
+   * 
+   * This allways returns first { link GXml.Namespace}'s prefix in { link GXml.Node}'s
+    * namespaces collection.
+   */
   public virtual string ns_prefix () { return namespaces.first ().prefix; }
+  /**
+   * Node's defaults namespace's URI.
+   * 
+   * This allways returns first { link GXml.Namespace}'s URI in { link GXml.Node}'s
+   * namespaces collection.
+   */
   public virtual string ns_urf () { return namespaces.first ().uri; }
+  /**
+   * Copy a { link GXml.Node} relaing on { link GXml.Document} to other { link GXml.Node}.
+   * 
+   * node could belongs from different { link GXml.Document}, while source is a node
+   * belonging to given document.
+   * 
+   * Just { link GXml.Element} objects are supported. For attributes, use
+   * { link GXml.Element.set_attr} method, passing source's name and value as arguments.
+   */
   public static bool copy (GXml.Document doc, GXml.Node node, GXml.Node source, bool deep)
   {
     if (node is GXml.Document) return false;