[gxml] * add documentation for Attr

[Richard Hans Schwarting <rschwart src gnome org>]

commit a9048be0b3613f457193fa999e6009c86ffb623a
Author: Richard Schwarting <aquarichy gmail com>
Date:   Thu Jul 21 14:35:54 2011 -0400

    * add documentation for Attr

 gxml/Attr.vala |   71 +++++++++++++++++++++++++++++++++++++++++++++++++------
 1 files changed, 63 insertions(+), 8 deletions(-)
---
diff --git a/gxml/Attr.vala b/gxml/Attr.vala
index 329ee5f..0ca2211 100644
--- a/gxml/Attr.vala
+++ b/gxml/Attr.vala
@@ -13,6 +13,12 @@
 /* NOTE: value as children nodes: can contain Text and EntityReferences */
 
 namespace GXml.Dom {
+	/**
+	 * Represents an XML Attr node. These represent name=value
+	 * attributes associated with XML Elements. Values are often
+	 * represented as strings but can also be subtrees for some
+	 * Nodes.  For more, see: [[http://www.w3.org/TR/DOM-Level-1/level-one-core.html#ID-637646024]]
+	 */
 	public class Attr : XNode {
 
 		/** Private properties */
@@ -26,7 +32,11 @@ namespace GXml.Dom {
 			this.specified = true;
 		}
 
-		/** Public properties (Node general) */
+		/* Public properties (Node general) */
+
+		/**
+		 * The node_name of an attribute is the attribute's name.
+		 */
 		public override string node_name {
 			get {
 				return this.node->name;
@@ -37,6 +47,11 @@ namespace GXml.Dom {
 
 		/* "raises [DomError] on setting/retrieval"?  */
 		private string _node_value;
+		/**
+		 * The node_value for an attribute is a string
+		 * representing the contents of the Attr's tree of
+		 * children.
+		 */
 		public override string? node_value {
 			/* If Attrs were always attached to elements, then it would have been
 			   nice to use elem.node->get/set_prop (name[,value])  :S */
@@ -44,6 +59,8 @@ namespace GXml.Dom {
 				this._node_value = "";
 				foreach (XNode child in this.child_nodes) {
 					this._node_value += child.node_value;
+					// TODO: verify that Attr node's child types'
+					// node_values are sufficient for building the Attr's value.
 				}
 				return this._node_value;
 			}
@@ -62,7 +79,10 @@ namespace GXml.Dom {
 			}
 		}
 
-
+		/**
+		 * { inheritDoc}
+		 */
+		/* already doc'd in XNode */
 		public override NodeList? child_nodes {
 			owned get {
 				// TODO: always create a new one?
@@ -72,9 +92,11 @@ namespace GXml.Dom {
 			}
 		}
 
+		/* Public properties (Attr-specific) */
 
-		/** Public properties (Attr-specific) */
-
+		/**
+		 * The name of the attribute's name=value pair. 
+		 */
 		public string name {
 			get {
 				// TODO: make sure that this is the right name, and that ownership is correct
@@ -84,12 +106,26 @@ namespace GXml.Dom {
 			}
 		}
 
-		// TODO: if 'specified' is to be set when 'value' is,
-		// add setter logic to 'value' property
+		/**
+		 * Whether an Attr was explicitly set in the
+		 * underlying document. If the attribute is changed,
+		 * it is set to false.
+		 *
+		 * #todo: this requires support from the DTD, and
+		 * probably libxml2's xmlAttribute
+		 */
 		public bool specified {
+			// STUB
 			get;
 			private set;
 		}
+
+		/**
+		 * Value of the Attr. This is the same as node_value.
+		 * It is a stringified version of the value, which can
+		 * also be accessed as a tree node structure of
+		 * child_nodes.
+		 */
 		public string value {
 			get {
 				return this.node_value;
@@ -99,22 +135,41 @@ namespace GXml.Dom {
 			}
 		}
 
-		/** Public methods (Node-specific) */
-		public override XNode? insert_before (XNode new_child, XNode ref_child) throws DomError {
+		/* Public methods (Node-specific) */
+
+		/**
+		 * { inheritDoc}
+		 */
+		public override XNode? insert_before (XNode new_child, XNode? ref_child) throws DomError {
 			return this.child_nodes.insert_before (new_child, ref_child);
 		}
+		/**
+		 * { inheritDoc}
+		 */
 		public override XNode? replace_child (XNode new_child, XNode old_child) throws DomError {
 			return this.child_nodes.replace_child (new_child, old_child);
 		}
+		/**
+		 * { inheritDoc}
+		 */
 		public override XNode? remove_child (XNode old_child) throws DomError {
 			return this.child_nodes.remove_child (old_child);
 		}
+		/**
+		 * { inheritDoc}
+		 */
 		public override XNode? append_child (XNode new_child) throws DomError {
 			return this.child_nodes.append_child (new_child);
 		}
+		/**
+		 * { inheritDoc}
+		 */
 		public override bool has_child_nodes () {
 			return (this.child_nodes.length > 0);
 		}
+		/**
+		 * { inheritDoc}
+		 */
 		public override XNode? clone_nodes (bool deep) {
 			return this; // STUB
 		}