[gxml] * document NodeType, Notation, ProcessingInstruction, Text and XNode

[Richard Hans Schwarting <rschwart src gnome org>]

commit 626494b5c7ab6627d0141fa513b538bfa16151fd
Author: Richard Schwarting <aquarichy gmail com>
Date:   Thu Jul 21 14:42:56 2011 -0400

    * document NodeType, Notation, ProcessingInstruction, Text and XNode

 gxml/NodeType.vala              |    5 ++
 gxml/Notation.vala              |   27 +++++++--
 gxml/ProcessingInstruction.vala |   21 +++++++
 gxml/Text.vala                  |   29 ++++++++++
 gxml/XNode.vala                 |  113 +++++++++++++++++++++++++++++++++++++-
 5 files changed, 186 insertions(+), 9 deletions(-)
---
diff --git a/gxml/NodeType.vala b/gxml/NodeType.vala
index 5b02662..c1bf186 100644
--- a/gxml/NodeType.vala
+++ b/gxml/NodeType.vala
@@ -1,6 +1,11 @@
 /* -*- Mode: vala; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */
 
 namespace GXml.Dom {
+	// TODO: want a method to convert NodeType to a string
+
+	/**
+	 * Enumerates possible NodeTypes. For more, see: [[http://www.w3.org/TR/DOM-Level-1/level-one-core.html#ID-1950641247]]
+	 */
 	public enum NodeType {
 		/* NOTE: bug in vala?  if I don't have == 0, I fail when creating
 		   this class because I can't set default values for NodeType properties
diff --git a/gxml/Notation.vala b/gxml/Notation.vala
index 62eb33c..f92dfbd 100644
--- a/gxml/Notation.vala
+++ b/gxml/Notation.vala
@@ -1,32 +1,47 @@
 /* -*- Mode: vala; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */
 
 namespace GXml.Dom {
+	// TODO: see if we can actually support these via libxml2, I can't seem to get to them through Xml.DTD
+	/**
+	 * Used collectively in defining DocumentTypes. A Notation can
+	 * declare the format of unparsed entities or
+	 * ProcessingInstruction targets.
+	 * For more, see: [[http://www.w3.org/TR/DOM-Level-1/level-one-core.html#ID-5431D1B9]]
+	 */
 	public class Notation : XNode {
 		// private Xml.Notation *notation; // TODO: wrap libxml's xmlNotation
 
+		/**
+		 * The declared name for the notation.
+		 */
 		public override string node_name {
 			get {
+				// TODO: needs to be set to the declared name of the notation
 				return ""; // notation->name;
 			}
 			private set {
 			}
 		}
-
-		public string public_id {
+		/**
+		 * The public identifier for the notation, or null if not set.
+		 */
+		public string? public_id {
 			get {
-				return ""; // notation->public_id;
+				return null; // notation->public_id;
 			}
 			private set {
 			}
 		}
-		public string system_id {
+		/**
+		 * The system identifier for the notation, or null if not set.
+		 */
+		public string? system_id {
 			get {
-				return ""; // notation->system_id;
+				return null; // notation->system_id;
 			}
 			private set {
 			}
 		}
-
 		internal Notation (/* Xml.Notation *notation, */ Document doc) {
 			base (NodeType.NOTATION, doc); // STUB
 			//this.notation = notation;
diff --git a/gxml/ProcessingInstruction.vala b/gxml/ProcessingInstruction.vala
index 6b5acb8..e64f42e 100644
--- a/gxml/ProcessingInstruction.vala
+++ b/gxml/ProcessingInstruction.vala
@@ -5,6 +5,14 @@ namespace GXml.Dom {
 	//       have a function to call when one is parsed.  Let's not
 	//       worry about supporting this for right now.
 
+	/**
+	 * Stores processor-specific information with the document in
+	 * a textual format. For example, with XML stylesheets:
+	 * {{{<?xml-stylesheet href="style.xsl" type="text/xml"?>}}}
+	 * The general form is
+	 * {{{<?pi_target processing instruction data?>}}}
+	 * For more, see: [[http://www.w3.org/TR/DOM-Level-1/level-one-core.html#ID-1004215813]]
+	 */
 	public class ProcessingInstruction : XNode {
 		internal ProcessingInstruction (string target, string data, Document doc) {
 			base (NodeType.PROCESSING_INSTRUCTION, doc); // TODO: want to pass a real Xml.Node* ?
@@ -12,14 +20,24 @@ namespace GXml.Dom {
 			this.data = data;
 		}
 
+		/**
+		 * The target for the processing instruction, like "xml-stylesheet".
+		 */
 		public string target {
 			get;
 			private set;
 		}
+		/**
+		 * The data used by the target, like {{{href="style.xsl" type="text/xml"}}}
+		 */
+		// TODO: confirm that data here is freeform attributes
 		public string data /* throws DomError (not supported yet) */ {
 			get;
 			set;	//throw new DomError.DOM ("Error");
 		}
+		/**
+		 * The target name.
+		 */
 		public override string node_name {
 			get {
 				return this.target;
@@ -27,6 +45,9 @@ namespace GXml.Dom {
 			private set {
 			}
 		}
+		/**
+		 * The target's data.
+		 */
 		public override string? node_value {
 			get {
 				return this.data;
diff --git a/gxml/Text.vala b/gxml/Text.vala
index f14b696..effaf05 100644
--- a/gxml/Text.vala
+++ b/gxml/Text.vala
@@ -2,10 +2,24 @@
 
 namespace GXml.Dom {
 	/* TODO: do we really want a text node, or just use strings? */
+
+	/**
+	 * Describes the text found as children of elements throughout
+	 * an XML document, like "He who must not be named" in the
+	 * XML: {{{<name>He who must not be named</name>}}}
+	 * With libxml2 as a backend, it should be noted that two
+	 * adjacent text nodes are always merged into one Text node,
+	 * so some functionality for Text, like split_text, will not
+	 * work completely as expected.
+	 * For more, see: [[http://www.w3.org/TR/DOM-Level-1/level-one-core.html#ID-1312295772]]
+	 */
 	public class Text : CharacterData {
 		internal Text (Xml.Node *text_node, Document doc) {
 			base (text_node, doc);
 		}
+		/**
+		 * The name of this node type, "#text"
+		 */
 		public override string node_name {
 			get {
 				return "#text"; // TODO: wish I could return "#" + base.node_name
@@ -14,6 +28,21 @@ namespace GXml.Dom {
 			}
 		}
 
+		/**
+		 * Normally, this would split the text into two
+		 * adjacent sibling Text nodes. Currently, with
+		 * libxml2, adjacent Text nodes are actually
+		 * automatically remerged, so for now, we split the
+		 * text and return the second part as a node outside
+		 * of the document tree.
+		 *
+		 * @param offset The point at which to split the Text,
+		 * in number of characters.
+		 *
+		 * @return The second half of the split Text node. For
+		 * now, it is not attached to the tree as a sibling to
+		 * the first part, as the spec wants.
+		 */
 		public Text split_text (ulong offset) throws DomError {
 			/* libxml2 doesn't handle this directly, in part because it doesn't
 			   allow Text siblings.  Boo! */
diff --git a/gxml/XNode.vala b/gxml/XNode.vala
index 747e447..c013421 100644
--- a/gxml/XNode.vala
+++ b/gxml/XNode.vala
@@ -1,6 +1,10 @@
 /* -*- Mode: vala; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */
 
 namespace GXml.Dom {
+	/**
+	 * Represents an XML Node. Documents are nodes, and are
+	 * composed of a tree of nodes. See [[http://www.w3.org/TR/DOM-Level-1/level-one-core.html#ID-1950641247]]
+	 */
 	public class XNode : GLib.Object {
 		internal XNode (NodeType type, Document owner) {
 			this.node_type = type;
@@ -11,6 +15,11 @@ namespace GXml.Dom {
 			this.node_type = NodeType.DOCUMENT;
 		}
 
+		/**
+		 * Stores the value of the Node. The nature of
+		 * node_value varies based on the type of node. This
+		 * can be null.
+		 */
 		public virtual string? node_value {
 			get {
 				return null;
@@ -19,12 +28,22 @@ namespace GXml.Dom {
 			}
 		}
 
+		/**
+		 * Stores the name of the node. Sometimes this is
+		 * similar to the node type, but sometimes, it is
+		 * arbitrary.
+		 */
 		public virtual string node_name {
 			get; internal set;
 		}
 
 
 		private NodeType _node_type;
+		/**
+		 * Stores the type of node. Most XML structures are
+		 * nodes of different types, like Document, Attr,
+		 * Element, etc.
+		 */
 		public virtual NodeType node_type {
 			get {
 				return _node_type;
@@ -36,37 +55,81 @@ namespace GXml.Dom {
 			}
 		}
 
+		/**
+		 * A link to the Document to which this node belongs.
+		 */
 		public Document owner_document {
 			get;
 			internal set;
 		}
 
 		// TODO: declare more of interface here
+		/**
+		 * A link to the parent of this node. For example,
+		 * with elements, the immediate, outer element is the parent.
+		 * <parent><child></child></parent>
+		 */
 		public virtual XNode? parent_node {
 			get { return null; }
 			internal set {}
 		}
+		/**
+		 * List of child nodes to this node. These sometimes
+		 * represent the value of a node as a tree of values,
+		 * whereas node_value represents it as a string. This
+		 * can be null for node types that have no children.
+		 *
+		 * The NodeList is live, in that changes to this
+		 * node's children will be reflected in an
+		 * already-active NodeList.
+		 *
+		 * #todo: list nodes that use children for values
+		 */
 		public virtual NodeList? child_nodes {
 			// TODO: need to implement NodeList
 			owned get { return null; }
 			internal set {}
 		}
+		/**
+		 * Links to the first child. If there are no
+		 * children, it returns null.
+		 */
 		public virtual XNode? first_child {
 			get { return null; }
 			internal set {}
 		}
+		/**
+		 * Links to the last child. If there are no
+		 * children, it returns null.
+		 */
 		public virtual XNode? last_child {
 			get { return null; }
 			internal set {}
 		}
+		/**
+		 * Links to this node's preceding sibling. If there
+		 * are no previous siblings, it returns null. Note
+		 * that the children of a node are ordered.
+		 */
 		public virtual XNode? previous_sibling {
 			get { return null; }
 			internal set {}
 		}
+		/**
+		 * Links to this node's next sibling. If there is no
+		 * next sibling, it returns null. Note that the
+		 * children of a node are ordered.
+		 */
 		public virtual XNode? next_sibling {
 			get { return null; }
 			internal set {}
 		}
+		/**
+		 * Returns a HashTable representing the attributes for
+		 * this node. Attributes actually only apply to
+		 * Element nodes. For all other types, attributes is
+		 * null.
+		 */
 		public virtual HashTable<string,Attr>? attributes {
 			get { return null; }
 			internal set {}
@@ -74,29 +137,73 @@ namespace GXml.Dom {
 
 		// These may need to be overridden by subclasses that support them.
 		// TODO: figure out what non-BackedNode classes should be doing with these, anyway
-		public virtual XNode? insert_before (XNode new_child, XNode ref_child) throws DomError {
+		/**
+		 * Insert new_child as a child to this node, and place
+		 * it in the list before ref_child. If ref_child is
+		 * null, new_child is appended to the list of children
+		 * instead.
+		 *
+		 * @throws DomError.NOT_FOUND if ref_child is not a valid child.
+		 */
+		// #todo: want to throw other relevant errors
+		public virtual XNode? insert_before (XNode new_child, XNode? ref_child) throws DomError {
 			return null;
 		}
+		/**
+		 * Replaces old_child with new_child in this node's list of children.
+		 *
+		 * @return The removed old_child.
+		 *
+		 * @throws DomError.NOT_FOUND if ref_child is not a valid child.
+		 */
 		public virtual XNode? replace_child (XNode new_child, XNode old_child) throws DomError {
 			return null;
 		}
+		/**
+		 * Removes old_child from this node's list of children.
+		 *
+		 * @return The removed old_child.
+		 *
+		 * @throws DomError.NOT_FOUND if old_child is not a valid child.
+		 * #todo: make @throws claim true
+		 */
 		public virtual XNode? remove_child (XNode old_child) throws DomError {
 			return null;
 		}
+		/**
+		 * Appends new_child to the end of this node's list of children.
+		 *
+		 * @return The newly added child.
+		 */
 		public virtual XNode? append_child (XNode new_child) throws DomError {
 			return null;
 		}
+		/**
+		 * Indicates whether this node has children.
+		 */
 		public virtual bool has_child_nodes () {
 			return false;
 		}
+		/**
+		 * Creates a parentless copy of this node.
+		 *
+		 * @param deep If true, descendants are cloned as
+		 * well. If false, they are not.
+		 *
+		 * @return A parentless clone of this node.
+		 */
 		public virtual XNode? clone_nodes (bool deep) {
 			return null;
-			// STUB
 		}
 
 		private string _str;
+		/**
+		 * Provides a string representation of this node.
+		 *
+		 * #todo: actually create a good, XML-ish one, will require overrides
+		 */
 		public string to_string () {
-			_str = "XNode(%s)".printf (this.node_name);
+			_str = "XNode(%d:%s)".printf (this.node_type, this.node_name);
 			return _str;
 		}
 	}