GNOME.org
 

[gxml] * some documentation fixes; more needed

commit 56b80b3a84d8920145a8dff78836e403c76fde81
Author: Richard Schwarting <aquarichy gmail com>
Date:   Mon Aug 13 15:48:01 2012 -0400

    * some documentation fixes; more needed

 gxml/Comment.vala      |   43 ++++++++++++++++++++++---------------------
 gxml/Document.vala     |   13 +++++++------
 gxml/DocumentType.vala |    2 +-
 gxml/DomError.vala     |   23 +++++++++--------------
 gxml/DomNode.vala      |    9 +++++----
 gxml/Element.vala      |    4 ++--
 gxml/Entity.vala       |   11 ++++++-----
 gxml/NodeList.vala     |   22 +++++++++++-----------
 gxml/Text.vala         |    2 ++
 9 files changed, 65 insertions(+), 64 deletions(-)
---
diff --git a/gxml/Comment.vala b/gxml/Comment.vala
index 4d3aada..7dedb59 100644
--- a/gxml/Comment.vala
+++ b/gxml/Comment.vala
@@ -1,26 +1,27 @@
 /* -*- Mode: vala; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */
-namespace GXml {
-	/* TODO: do we really want a comment node, or just use strings? */
-	/**
-	 * An XML comment. An XML example looks like: {{{
-	 * <someNode>
-	 *    <!-- this is a comment -->
-	 *    text in the node
-	 *  </someNode> }}}
-	 * For more, see: [[http://www.w3.org/TR/DOM-Level-1/level-one-core.html#ID-1728279322]]
-	 */
-	public class Comment : CharacterData {
-		// TODO: Can I make this only accessible from within the GXml.Dom namespace (e.g. from GXml.Dom.Document?)
-		internal Comment (Xml.Node *comment_node, Document doc) {
-			base (comment_node, doc);
+
+/* TODO: do we really want a comment node, or just use strings? */
+/**
+ * An XML comment.
+ *
+ * An XML example looks like: {{{
+ * <someNode>
+ *    &lt;!-- this is a comment -->
+ *    text in the node
+ *  </someNode> }}}
+ * For more, see: [[http://www.w3.org/TR/DOM-Level-1/level-one-core.html#ID-1728279322]]
+ */
+public class GXml.Comment : GXml.CharacterData {
+	// TODO: Can I make this only accessible from within the GXml.Dom namespace (e.g. from GXml.Dom.Document?)
+	internal Comment (Xml.Node *comment_node, Document doc) {
+		base (comment_node, doc);
+	}
+	public override string node_name {
+		get {
+			return "#comment";
 		}
-		public override string node_name {
-			get {
-				return "#comment";
-			}
-			private set {
-			}
+		private set {
 		}
-
 	}
+
 }
diff --git a/gxml/Document.vala b/gxml/Document.vala
index 5f9d288..cd4c3e3 100644
--- a/gxml/Document.vala
+++ b/gxml/Document.vala
@@ -39,10 +39,11 @@ namespace GXml {
 	}
 
 	/**
-	 * Represents an XML Document as a tree of nodes. The Document
-	 * has a document element, which is the root of the tree. A
-	 * Document can have its type defined by a DocumentType. For
-	 * more, see:
+	 * Represents an XML Document as a tree of { link GXml.DomNode}s.
+	 *
+	 * The Document has a document element, which is the root of
+	 * the tree. A Document can have its type defined by a
+	 * { link GXml.DocumentType}. For more, see:
 	 * [[http://www.w3.org/TR/DOM-Level-1/level-one-core.html#i-Document]]
 	 */
 	public class Document : DomNode {
@@ -483,8 +484,8 @@ namespace GXml {
 		}
 		/**
 		 * Creates an entity reference. XML example:
-		 * {{{&name;
-		 * &apos;}}}
+		 * {{{&amp;name;
+		 * &amp;apos;}}}
 		 */
 		public EntityReference create_entity_reference (string name) throws DomError {
 			check_html ("entity reference"); // TODO: i18n
diff --git a/gxml/DocumentType.vala b/gxml/DocumentType.vala
index 56ef13b..e9e595d 100644
--- a/gxml/DocumentType.vala
+++ b/gxml/DocumentType.vala
@@ -23,7 +23,7 @@ namespace GXml {
 		/**
 		 * That which follows DOCTYPE, like 'xml' or 'html', For example, the name
 		 * 'html' exists for a document with the XML doctype
-		 * declaration of {{{ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd";> }}}
+		 * declaration of {{{ &lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd";> }}}
 		*/
 		public string name {
 			get {
diff --git a/gxml/DomError.vala b/gxml/DomError.vala
index e62c869..a348df1 100644
--- a/gxml/DomError.vala
+++ b/gxml/DomError.vala
@@ -1,20 +1,16 @@
 /* -*- Mode: vala; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */
 
-/* implements DomException
-   note usage at:
-   http://www.w3.org/TR/DOM-Level-1/level-one-core.html#ID-BBACDC08 */
-namespace GXml {
+/**
+ * Describes various error states. For more, see
+ * [[http://www.w3.org/TR/DOM-Level-1/level-one-core.html#ID-BBACDC08]]
+ */
+public errordomain GXml.DomError {
+	/* These error codes are from the IDL: TODO: find out when I should use them */
+	/* TODO: probably want to document them :) */
 	/**
-	 * Describes various error states. For more, see
-	 * [[http://www.w3.org/TR/DOM-Level-1/level-one-core.html#ID-BBACDC08]]
+	 * An index or size is out of range, like less than 0 or exceeding some upper bound.
 	 */
-	public errordomain DomError {
-		/* These error codes are from the IDL: TODO: find out when I should use them */
-		/* TODO: probably want to document them :) */
-		/**
-		 * An index or size is out of range, like less than 0 or exceeding some upper bound.
-		 */
-		INDEX_SIZE,
+	INDEX_SIZE,
 		/**
 		 * Text exceeds the maximum size supported in our string implementation.
 		 */ // TODO: figure out what the limits of strings are in vala
@@ -66,5 +62,4 @@ namespace GXml {
 		 * A document lacked a root element.
 		 */
 		INVALID_ROOT
-	}
 }
diff --git a/gxml/DomNode.vala b/gxml/DomNode.vala
index 417e568..ef1a4a2 100644
--- a/gxml/DomNode.vala
+++ b/gxml/DomNode.vala
@@ -197,10 +197,11 @@ namespace GXml {
 			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.
+		 * A { link GLib.HashTable} representing the
+		 * attributes for this node. `attributes` actually
+		 * only apply to { link GXml.Element} nodes. For all
+		 * other { link GXml.DomNode} subclasses, `attributes`
+		 * is null.
 		 */
 		public virtual HashTable<string,Attr>? attributes {
 			get { return null; }
diff --git a/gxml/Element.vala b/gxml/Element.vala
index 0745eaa..48de838 100644
--- a/gxml/Element.vala
+++ b/gxml/Element.vala
@@ -172,7 +172,7 @@ namespace GXml {
 		 * attribute associated with this element with the
 		 * name name.
 		 *
-		 * @param The name of the attribute whose value to retrieve.
+		 * @param name The name of the attribute whose value to retrieve.
 		 *
 		 * @return The value of the named attribute, or "" if
 		 * no such attribute is set.
@@ -234,7 +234,7 @@ namespace GXml {
 		/**
 		 * Set the attribute in Attr for this element.
 		 *
-		 * @param Attr The attribute to set.
+		 * @param new_attr The attribute to set.
 		 *
 		 * @return If an Attr with the same name exists, it
 		 * is replaced and the old Attr is returned.
diff --git a/gxml/Entity.vala b/gxml/Entity.vala
index fe1836d..ff82a60 100644
--- a/gxml/Entity.vala
+++ b/gxml/Entity.vala
@@ -1,15 +1,16 @@
 /* -*- Mode: vala; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */
 namespace GXml {
 	/**
-	 * The content referenced by an EntityReference, and defined
-	 * in a DocumentType.
+	 * The content referenced by an { link GXml.EntityReference}, and defined
+	 * in a { link GXml.DocumentType}.
+	 * 
 	 * For more, see: [[http://www.w3.org/TR/DOM-Level-1/level-one-core.html#ID-11C98490]]
 	 */
 	public class Entity : DomNode {
 		private Xml.Entity *entity;
 
 		/**
-		 * A public identifier for the entity. null when unspecified.
+		 * A public identifier for the entity. `null` when unspecified.
 		 */ // TODO: how are these used?
 		public string public_id {
 			get {
@@ -20,7 +21,7 @@ namespace GXml {
 			}
 		}
 		/**
-		 * A system identifier for the entity. null when unspecified.
+		 * A system identifier for the entity. `null` when unspecified.
 		 */
 		public string system_id {
 			get {
@@ -32,7 +33,7 @@ namespace GXml {
 		}
 		/**
 		 * The notation name for this entity if it is
-		 * unparsed. This is null if the entity is parsed.
+		 * unparsed. This is `null` if the entity is parsed.
 		 */
 		public string notation_name {
 			get {
diff --git a/gxml/NodeList.vala b/gxml/NodeList.vala
index 194938e..e0c8033 100644
--- a/gxml/NodeList.vala
+++ b/gxml/NodeList.vala
@@ -28,7 +28,7 @@ namespace GXml {
 		 * TODO: figure out how to require this as a property; maybe have to make it into a method
 		 */
 
-		/*** GNOME List conventions ***
+		/* ** GNOME List conventions ***
 		 * Probably don't want to keep all of them since they're not all relevant.
 		 */
 		/**
@@ -212,7 +212,7 @@ namespace GXml {
 			return str;
 		}
 
-		/*** Traversable methods ***/
+		/* ** Traversable methods ** */
 
 		/* TODO: Verify that relying on these *_impl methods is appropriate */
 		public Iterator<DomNode> chop (int offset, int length = -1) {
@@ -229,7 +229,7 @@ namespace GXml {
 			return Iterator.stream_impl<DomNode, A> (this.iterator (), f);
 		}
 
-		/*** Iterable methods ***/
+		/* ** Iterable methods ***/
 		public GLib.Type element_type {
 			get {
 				return typeof (DomNode);
@@ -280,7 +280,7 @@ namespace GXml {
 				this.next_node = this.cur.next;
 			}
 
-			/*** Traversable methods ***/
+			/* ** Traversable methods ** */
 
 			public override void foreach (ForallFunc<DomNode> f) {
 				/* TODO: we need to iterate over the items in the iterator,
@@ -618,7 +618,7 @@ namespace GXml {
 			return _str;
 		}
 
-		/*** Traversable methods ***/
+		/* ** Traversable methods ***/
 
 		/* TODO: Verify that relying on these *_impl methods is appropriate */
 		public Iterator<DomNode> chop (int offset, int length = -1) {
@@ -634,7 +634,7 @@ namespace GXml {
 			return Iterator.stream_impl<DomNode, A> (this.iterator (), f);
 		}
 
-		/*** NodeListIterator ***/
+		/* ** NodeListIterator ***/
 
 		private class NodeListIterator : GenericNodeListIterator {
 			private Document doc;
@@ -651,7 +651,7 @@ namespace GXml {
 				this.doc = list.owner;
 			}
 
-			/*** model-specific methods ***/
+			/* ** model-specific methods ***/
 
 			protected override DomNode get_current () {
 				return this.doc.lookup_node (this.cur);
@@ -666,7 +666,7 @@ namespace GXml {
 				this.next_node = cur->next;
 			}
 
-			/*** Traversable methods ***/
+			/* ** Traversable methods ***/
 
 			public override void foreach (ForallFunc<DomNode> f) {
 				/* TODO: we need to iterate over the items in the iterator,
@@ -685,12 +685,12 @@ namespace GXml {
 		}
 	}
 
-	public abstract class GenericNodeListIterator : Gee.Traversable<DomNode>, Gee.Iterator<DomNode>, GLib.Object {
+	private abstract class GenericNodeListIterator : Gee.Traversable<DomNode>, Gee.Iterator<DomNode>, GLib.Object {
 		protected abstract DomNode get_current ();
 		protected abstract bool is_empty ();
 		protected abstract void advance ();
 
-		/*** Traversable methods ***/
+		/* ** Traversable methods ***/
 
 		public Gee.Iterator<DomNode> chop (int offset, int length = -1) {
 			/* TODO: is this how the *_impl static methods in Iterator and
@@ -712,7 +712,7 @@ namespace GXml {
 
 		public abstract void foreach (ForallFunc<DomNode> f);
 
-		/*** Iterator methods ***/
+		/* ** Iterator methods ***/
 
 		/**
 		 * Obtain the current DomNode in the iteration.
diff --git a/gxml/Text.vala b/gxml/Text.vala
index 5183e35..61ecf53 100644
--- a/gxml/Text.vala
+++ b/gxml/Text.vala
@@ -3,6 +3,8 @@ namespace GXml {
 	/* TODO: do we really want a text node, or just use strings? */
 
 	/**
+	 * Text children of an element, not the tags or attributes.
+	 *
 	 * 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>}}}
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]