[gxml] * document Entity, EntityReference, Implementation

[Richard Hans Schwarting <rschwart src gnome org>]

commit 4a9fa267449f94d2c8e89415f48d79e7770fd390
Author: Richard Schwarting <aquarichy gmail com>
Date:   Thu Jul 21 14:41:26 2011 -0400

    * document Entity, EntityReference, Implementation

 gxml/Entity.vala          |   21 ++++++++++++++++++---
 gxml/EntityReference.vala |   11 +++++++++++
 gxml/Implementation.vala  |   16 ++++++++++++++++
 3 files changed, 45 insertions(+), 3 deletions(-)
---
diff --git a/gxml/Entity.vala b/gxml/Entity.vala
index 7198fd4..8868eff 100644
--- a/gxml/Entity.vala
+++ b/gxml/Entity.vala
@@ -1,9 +1,17 @@
 /* -*- Mode: vala; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */
 
 namespace GXml.Dom {
+	/**
+	 * The content referenced by an EntityReference, and defined
+	 * in a DocumentType.
+	 * For more, see: [[http://www.w3.org/TR/DOM-Level-1/level-one-core.html#ID-11C98490]]
+	 */
 	public class Entity : XNode {
 		private Xml.Entity *entity;
 
+		/**
+		 * A public identifier for the entity. null when unspecified.
+		 */ // TODO: how are these used?
 		public string public_id {
 			get {
 				//return this.entity->external_id; // TODO: fix libxml2 wrapper
@@ -12,6 +20,9 @@ namespace GXml.Dom {
 			private set {
 			}
 		}
+		/**
+		 * A system identifier for the entity. null when unspecified.
+		 */
 		public string system_id {
 			get {
 				// return this.entity->system_id; // TODO: fix libxml2 wrapper
@@ -20,6 +31,10 @@ namespace GXml.Dom {
 			private set {
 			}
 		}
+		/**
+		 * The notation name for this entity if it is
+		 * unparsed. This is null if the entity is parsed.
+		 */
 		public string notation_name {
 			get {
 				// parsed: return null
@@ -38,7 +53,7 @@ namespace GXml.Dom {
 			this.entity = entity;
 		}
 
-		/** Public properties (Node-specific) */
+		/* Public properties (Node-specific) */
 
 		public override string node_name {
 			get {
@@ -70,8 +85,8 @@ namespace GXml.Dom {
 			}
 		}
 
-		/** Public methods (Node-specific) */
-		public override XNode? insert_before (XNode new_child, XNode ref_child) throws DomError {
+		/* Public methods (Node-specific) */
+		public override XNode? insert_before (XNode new_child, XNode? ref_child) throws DomError {
 			return this.child_nodes.insert_before (new_child, ref_child);
 		}
 		public override XNode? replace_child (XNode new_child, XNode old_child) throws DomError {
diff --git a/gxml/EntityReference.vala b/gxml/EntityReference.vala
index 1b92e4c..d4d0ec1 100644
--- a/gxml/EntityReference.vala
+++ b/gxml/EntityReference.vala
@@ -4,12 +4,23 @@ namespace GXml.Dom {
 	/* TODO: do we need an EntityReference? find out what it's used for */
 	// TODO: figure out some way to represent this from libxml2, or handle it ourselves
 	//       may not even need it while based on libxml2
+	// It's possible that libxml2 already expands entity references and that this class
+	// won't be used
+	/**
+	 * A reference to an unparsed entity, like "&apos;" for an apostrophe.
+	 * For more, see: [[http://www.w3.org/TR/DOM-Level-1/level-one-core.html#ID-11C98490]]
+	 */
+	// TODO: make sure that character entity references (like the one used in the example above, are valid
 	public class EntityReference : XNode {
 		internal EntityReference (string refname, Document doc) {
 			// TODO: may want to handle refname differently
 			base (NodeType.ENTITY_REFERENCE, doc); // TODO: what should we pass up?
 			this.node_name = refname;
 		}
+		/**
+		 * Stores the reference entity's name ("apos" for &apos;).
+		 */
+		// TODO: not sure if that's correct ^
 		public override string node_name {
 			get;
 			private set;
diff --git a/gxml/Implementation.vala b/gxml/Implementation.vala
index 0774dd7..6dec3cd 100644
--- a/gxml/Implementation.vala
+++ b/gxml/Implementation.vala
@@ -1,10 +1,26 @@
 /* -*- Mode: vala; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */
 
 namespace GXml.Dom {
+	/**
+	 * Describes the features available in this
+	 * implementation. This can be accessed from a Document
+	 * object. Provided a possible feature and the feature's
+	 * version, it can tell the client whether it is here
+	 * implemented.
+	 * For more, see: [[http://www.w3.org/TR/DOM-Level-1/level-one-core.html#ID-102161490]]
+	 */
 	public class Implementation {
 		internal Implementation () {
 		}
 
+		/**
+		 * Reports whether we support a feature at a given version level.
+		 *
+		 * @param feature A feature we might support, usually something like 'xml' or 'html'.
+		 * @param version A possible version of the feature, or null if any version will do.
+		 *
+		 * @return true if we support the specified feature, false otherwise.
+		 */
 		public bool has_feature (string feature, string? version) {
 			/* Level 1 is limited to "xml" and "html" (icase) */
 			switch (feature) {