GNOME.org
 

[gxml] * document Element

commit 92fafc7e15fe71c89cd472d56f612c21009b6fe6
Author: Richard Schwarting <aquarichy gmail com>
Date:   Thu Jul 21 14:40:44 2011 -0400

    * document Element

 gxml/Element.vala |  149 +++++++++++++++++++++++++++++++++++++++++++++++------
 1 files changed, 132 insertions(+), 17 deletions(-)
---
diff --git a/gxml/Element.vala b/gxml/Element.vala
index 4bae035..2a256e2 100644
--- a/gxml/Element.vala
+++ b/gxml/Element.vala
@@ -3,8 +3,29 @@
 namespace GXml.Dom {
 	// TODO: figure out how to create this; Xml.Doc doesn't have new_element()
 
+	/**
+	 * Represent an XML Element node. These can have child nodes
+	 * of various types including other Elements. Elements can
+	 * have Attr attributes associated with them. Elements have
+	 * tag names. In addition to methods inherited from XNode,
+	 * Elements have additional methods for manipulating
+	 * attributes, as an alternative to manipulating the
+	 * attributes HashMap directly. For more, see:
+	 * [[http://www.w3.org/TR/DOM-Level-1/level-one-core.html#ID-745549614]]
+	 */
 	public class Element : BackedNode {
-		/** Public properties */
+		/* Public properties */
+
+		// TODO: find out how to do double-spaces in Valadoc, so we can indent <img...
+		/**
+		 * The element's tag_name. Multiple elements can have
+		 * the same tag name in a document. XML example:
+		 * {{{<photos>
+		 *   <img src="..." />
+		 *   <img src="..." />
+		 * </photos>}}}
+		 * In this example, photos and img are tag names.
+		 */
 		public string tag_name {
 			get {
 				// This is the same as node_name from Node:
@@ -15,6 +36,11 @@ namespace GXml.Dom {
 			private set {
 			}
 		}
+		/**
+		 * Elements do not have a node_value. Instead, their
+		 * contents are stored in Attr attributes and in
+		 * child_nodes.
+		 */
 		public override string? node_value {
 			get {
 				return null;
@@ -26,6 +52,25 @@ namespace GXml.Dom {
 		/* HashTable used for XML NamedNodeMap */
 		// TODO: note that NamedNodeMap is 'live' so changes to the Node should be seen in the NamedNodeMap (already retrieved), no duplicating it: http://www.w3.org/TR/DOM-Level-1/level-one-core.html
 		private HashTable<string,Attr> _attributes = new HashTable<string,Attr> (GLib.str_hash, GLib.str_equal); // TODO: make sure other HashTables have appropriate hash, equal functions
+
+		/**
+		 * Contains a HashTable of Attr attributes associated with this element.
+		 *
+		 * Attributes in the HashTable are updated live, so
+		 * changes in the element's attributes through its
+		 * other methods are reflected in the attributes
+		 * HashTable.
+		 */
+		/*
+		 * #todo: verify that because we're giving them a
+		 * reference to our own attributes HashTable for
+		 * manipulating, that our methods do keep it live, so
+		 * we don't need to implement NamedNodeMap.
+		 *
+		 * #todo: make sure we fill our _attributes at
+		 * construction time with the attributes from the
+		 * document.
+		 */
 		public override HashTable<string,Attr>? attributes {
 			// TODO: make sure we want the user to be able to manipulate attributes using this HashTable. // Yes, we do, it should be a live reflection
 			// TODO: remember that this table needs to be synced with libxml2 structures; perhaps use a flag that indicates whether it was even accessed, and only then sync it later on
@@ -43,15 +88,26 @@ namespace GXml.Dom {
 		}
 
 
-		/** Constructors */
+		/* Constructors */
 		internal Element (Xml.Node *node, Document doc) {
 			base (node, doc);
 			// TODO: consider string ownership, libxml2 memory
 			// TODO: do memory testing
 		}
 
-		/** Public Methods */
+		/* Public Methods */
 		// TODO: for base.attribute-using methods, how do I re-sync base.attributes with Xml.Node* attributes?
+
+		/**
+		 * Retrieve the attribute value, as a string, for an
+		 * attribute associated with this element with the
+		 * name name.
+		 *
+		 * @param The name of the attribute whose value to retrieve.
+		 *
+		 * @return The value of the named attribute, or "" if
+		 * no such attribute is set.
+		 */
 		public string get_attribute (string name) {
 			// should I used .attributes.lookup (name)?
 			Attr attr = this.attributes.lookup (name);
@@ -61,6 +117,13 @@ namespace GXml.Dom {
 			else
 				return ""; // IDL says empty string, TODO: consider null instead
 		}
+		/**
+		 * Set the value of this element's attribute named
+		 * name to the string value.
+		 *
+		 * @param name Name of the attribute whose value to set.
+		 * @param value The value to set.
+		 */
 		public void set_attribute (string name, string value) throws DomError {
 			// don't need to use insert
 			Attr attr = this.attributes.lookup (name);
@@ -75,29 +138,59 @@ namespace GXml.Dom {
 			// TODO: replace wanted 'owned', look up what to do
 
 		}
+		/**
+		 * Remove the attribute named name from this element.
+		 *
+		 * @param name The name of the attribute to unset.
+		 */
 		public void remove_attribute (string name) throws DomError {
 			this.attributes.remove (name);
 		}
-		public Attr get_attribute_node (string name) {
-			// rightfully returns NULL if it does not exist
+		/**
+		 * Get the Attr node representing this element's attribute named name.
+		 *
+		 * @param name The name of the Attr node to retrieve.
+		 *
+		 * @return The Attr node named by name for this element.
+		 */
+		public Attr? get_attribute_node (string name) {
+
+			// TODO: verify that attributes returns null with unknown name
 			return this.attributes.lookup (name);
 		}
+		/**
+		 * Set the attribute in Attr for this element.
+		 *
+		 * @param Attr The attribute to set.
+		 *
+		 * @return If an Attr with the same name exists, it
+		 * is replaced and the old Attr is returned.
+		 * Elsewise, null is returned.
+		 */
 		public Attr set_attribute_node (Attr new_attr) throws DomError {
 			// TODO: need to actually associate this with the libxml2 structure!
+			// TODO: need to do that at the time of saving. We don't right now :|
 			Attr old = this.attributes.lookup (new_attr.name);
 			this.attributes.replace (new_attr.name, new_attr);
 			return old;
 		}
-		public Attr remove_attribute_node (Attr old_attr) throws DomError {
-			// TODO: need to check for nulls
 
+		/**
+		 * Remove Attr old_attr from this element, if it was
+		 * set.
+		 *
+		 * @param old_attr The Attr we are removing.
+		 *
+		 * @return The old_attr we wanted to remove, even if
+		 * it wasn't found.
+		 */
+		public Attr remove_attribute_node (Attr old_attr) throws DomError {
+			// TODO: need to check for nulls. < Nope, ? controls that.
 			this.attributes.remove (old_attr.name);
-			return old_attr; // TODO: is this what we want to return?
+			return old_attr;
 		}
 
-		// TODO: somewhere want to make clear that node_value does not contain the contents of a node, but that its text children do :)
-
-		/*
+		/* Visual explanation of get_elements_by_tag_name tree traversal.
 		     a
 		   b    c
 		  d e  f g
@@ -122,7 +215,22 @@ namespace GXml.Dom {
 
 		  see a, add a, visit a
 		*/
-		public List<XNode> get_elements_by_tag_name (string name) {
+
+		/**
+		 * Obtains a NodeList of Elements with the given
+		 * tag_name that are descendants of this Element.
+		 * This will include the current element if it
+		 * matches. The returned list is updated as necessary
+		 * as the tree changes.
+		 *
+		 * @param tag_name The tag name to match for.
+		 *
+		 * @return A NOdeList containing the matching descendants.
+		 */
+		/*TODO: make sure we want to include the current
+		 * element, I think probably not.
+		 */
+		public List<XNode> get_elements_by_tag_name (string tag_name) {
 			List<XNode> tagged = new List<XNode> ();
 			Queue<Xml.Node*> tocheck = new Queue<Xml.Node*> ();
 
@@ -133,7 +241,7 @@ namespace GXml.Dom {
 			while (tocheck.is_empty () == false) {
 				Xml.Node *cur = tocheck.pop_head ();
 
-				if (cur->name == name) {
+				if (cur->name == tag_name) {
 					tagged.append (this.owner_document.lookup_node (cur));
 				}
 
@@ -145,11 +253,17 @@ namespace GXml.Dom {
 			return tagged;
 		}
 
-		/* This merges all Text nodes that are adjacent to one
-		 * another for the descendents of this Element */
+		/**
+		 * This merges all adjacent Text nodes that are
+		 * descendants of this element. Sibling Text nodes
+		 * are not distinguishable in XML when stored outside
+		 * of the DOM.
+		 */
 		public void normalize () {
-			// TODO: do not normalise CDATASection which inherits from Text
-			//       don't think that will be a problem, given that it will have a different .node_tyep
+			// TODO: do not normalise CDATASection which
+			//       inherits from Text don't think that
+			//       will be a problem, given that it will
+			//       have a different .node_type
 
 			// STUB
 
@@ -160,6 +274,7 @@ namespace GXml.Dom {
 					break;
 				case NodeType.TEXT:
 					// TODO: check siblings: what happens in vala when you modify a list you're iterating?
+					// TODO: I think libxml2 automatically normalises adjacent text nodes, which is kind of annoying.
 					// STUB
 					break;
 				}
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]