[gxml] Collection: improved documentation and error messages

[Daniel Espinosa Ortiz <despinosa src gnome org>]

commit b66fffce381e0bcacda9515137509de69726f73e
Author: Daniel Espinosa <esodan gmail com>
Date:   Tue Jul 9 13:55:51 2019 -0500

    Collection: improved documentation and error messages

 gxml/Collections.vala | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++-
 gxml/Parser.vala      |  6 +++++-
 2 files changed, 56 insertions(+), 2 deletions(-)
---
diff --git a/gxml/Collections.vala b/gxml/Collections.vala
index 2fc6a29..be227a5 100644
--- a/gxml/Collections.vala
+++ b/gxml/Collections.vala
@@ -23,7 +23,57 @@
 using Gee;
 
 /**
- * A DOM4 interface to keep references to {@link DomElement} children of a {@link element}
+ * A DOM4 interface to keep references to {@link DomElement} children of a {@link element}.
+ *
+ * A collection should call {@link initialize} with the object's type to be added to
+ * the connection and, at construction time, set the {@link element} this collection
+ * should take its members from.
+ *
+ * This way, you can have a property to access all child elements of a given type,
+ * the node will be added automatically to both as a child of your element and as
+ * a member of the collection.
+ *
+ * {{{
+ *   // This is your object definition and a collection one
+ *   public class YourObject : GXml.Element {
+ *    [Description (nick="::Name")]
+ *    public string name { get; set; }
+ *    construct {
+ *      // This is the Element's node's name to be used
+ *      try { initialize ("NodeName"); }
+ *      catch (GLib.Error e ) {
+ *        warning ("Error: "+e.message);
+ *      }
+ *    }
+ *   }
+ *   public class YourList : GXml.ArrayList {
+ *    construct {
+ *      // With this, your collection will find a add all elements
+ *      // with the node's name 'NodeName' as declared to YourObject class
+ *      try { initialize (typeof (YourObject)); }
+ *      catch (GLib.Error e) {
+ *        warning ("Initialization error for collection type: %s : %s"
+ *             .printf (get_type ().name(), e.message));
+ *      }
+ *    }
+ *   }
+ *   // This is your element object definition with a collection of nodes
+ *   // with the type YourObject
+ *   public class YourElement : GXml.Element {
+ *     public YourObject.YourList your_objects { get; set; }
+ *     construct {
+ *       // This is initializing the property 'your_objects' which is the type
+ *       // YourList collection and set YourElement object as its element to
+ *       // to take its members from. Use canonical names for properties as shown
+ *       set_instance_property ('your-objects');
+ *       // This is the node's name to use for YourElement class
+ *        try { initialize ("YourElement"); }
+ *        catch (GLib.Error e) {
+ *          warning ("Initialization error for element type: %s", e.message));
+ *        }
+ *      }
+ *    }
+ * }}}
  */
 public interface GXml.Collection : GLib.Object
 {
diff --git a/gxml/Parser.vala b/gxml/Parser.vala
index b86ecaa..409675f 100644
--- a/gxml/Parser.vala
+++ b/gxml/Parser.vala
@@ -258,7 +258,11 @@ public interface GXml.Parser : GLib.Object {
       }
       if (col.element == null || !(col.element is GXml.Object)) {
         throw new DomError.INVALID_NODE_TYPE_ERROR
-                    (_("Invalid Element set to Collection"));
+                    (_("Collection hasn't been constructed properly: element property was not set at 
construction time"));
+      }
+      if (!(col.element is GXml.Object)) {
+        throw new DomError.INVALID_NODE_TYPE_ERROR
+                    (_("Invalid object's type '%s' it doesn't implemement GXml.Object interface: can't be 
handled by the collection"), col.element.get_type ().name ());
       }
       if (col.items_name.down () == current_node_name ().down ()) {
         if (parent.owner_document == null)