[gxml] Collection: improved documentation and error messages
- From: Daniel Espinosa Ortiz <despinosa src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gxml] Collection: improved documentation and error messages
- Date: Tue, 9 Jul 2019 18:58:51 +0000 (UTC)
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)
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]