[gxml] * clean up documentation, add more links, escape < in examples
- From: Richard Hans Schwarting <rschwart src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gxml] * clean up documentation, add more links, escape < in examples
- Date: Wed, 15 Aug 2012 01:32:33 +0000 (UTC)
commit 83243eef7c0a439c31dc1c77eb84e4ef8c8cbde2
Author: Richard Schwarting <aquarichy gmail com>
Date: Tue Aug 14 10:11:23 2012 -0400
* clean up documentation, add more links, escape < in examples
gxml/Attr.vala | 12 ++++++---
gxml/BackedNode.vala | 7 +++--
gxml/CDATASection.vala | 8 +++++-
gxml/CharacterData.vala | 8 +++++-
gxml/Comment.vala | 6 +++-
gxml/Document.vala | 12 +++++-----
gxml/DocumentFragment.vala | 18 +++++++++------
gxml/DocumentType.vala | 1 +
gxml/DomNode.vala | 21 +++++++++++------
gxml/Element.vala | 34 ++++++++++++++++------------
gxml/EntityReference.vala | 7 +++++-
gxml/Implementation.vala | 4 ++-
gxml/NamespaceAttr.vala | 8 ++++--
gxml/NodeList.vala | 5 ++-
gxml/NodeType.vala | 46 +++++++++++++++++++-------------------
gxml/Notation.vala | 2 +
gxml/ProcessingInstruction.vala | 11 ++++++--
gxml/Serializable.vala | 7 ++---
gxml/Text.vala | 4 ++-
19 files changed, 134 insertions(+), 87 deletions(-)
---
diff --git a/gxml/Attr.vala b/gxml/Attr.vala
index f400d36..29b84be 100644
--- a/gxml/Attr.vala
+++ b/gxml/Attr.vala
@@ -15,10 +15,14 @@
[CCode (gir_namespace = "GXml", gir_version = "0.2")]
namespace GXml {
/**
- * 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]]
+ * Represents an XML Attr node, a name=value pair.
+ *
+ * To create one, use { link GXml.Document.create_attribute}.
+ *
+ * These represent name=value attributes associated with XML
+ * { link GXml.Element}s. Values are often represented as strings but can
+ * also be more complex subtrees for some nodes. For more, see:
+ * [[http://www.w3.org/TR/DOM-Level-1/level-one-core.html#ID-637646024]]
*/
public class Attr : DomNode {
/**
diff --git a/gxml/BackedNode.vala b/gxml/BackedNode.vala
index e013a06..2cbfdc3 100644
--- a/gxml/BackedNode.vala
+++ b/gxml/BackedNode.vala
@@ -5,9 +5,10 @@
namespace GXml {
/**
* An internal class for nodes whose content is stored in a
- * corresponding Xml.Node. This would normally be hidden, but
- * Vala wants base classes to be at least as public as
- * subclasses.
+ * corresponding Xml.Node.
+ *
+ * This would normally be hidden, but Vala wants base classes
+ * to be at least as public as subclasses.
*/
public class BackedNode : DomNode {
/** Private properties */
diff --git a/gxml/CDATASection.vala b/gxml/CDATASection.vala
index 89e8ced..d8fb258 100644
--- a/gxml/CDATASection.vala
+++ b/gxml/CDATASection.vala
@@ -5,8 +5,12 @@ namespace GXml {
/* TODO: check about casing in #vala */
/**
* An XML CDATA section, which contains non-XML data that is
- * stored in an XML document. An XML example would be like:
- * {{{ <![CDATA[Here contains non-XML data, like code, or something that
+ * stored in an XML document.
+ *
+ * To create one, use { link GXml.Document.create_cdata_section}.
+ *
+ * An XML example would be like:
+ * {{{ <![CDATA[Here contains non-XML data, like code, or something that
* requires a lot of special XML entities.]]>. }}}
* It is a type of Text node. For more, see: [[http://www.w3.org/TR/DOM-Level-1/level-one-core.html#ID-667469212]]
*/
diff --git a/gxml/CharacterData.vala b/gxml/CharacterData.vala
index 32ddbb1..8e2d817 100644
--- a/gxml/CharacterData.vala
+++ b/gxml/CharacterData.vala
@@ -1,8 +1,12 @@
/* -*- Mode: vala; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */
namespace GXml {
/**
- * CharacterData defines an interface for manipulating XML character data. It is used by
- * the CDATASection, Text, and Comment node types. For more, see: [[http://www.w3.org/TR/DOM-Level-1/level-one-core.html#ID-FF21A306]]
+ * CharacterData defines an interface for manipulating XML character data.
+ *
+ * It is used by the { link GXml.CDATASection},
+ * { link GXml.Text}, and { link GXml.Comment} node types. For more,
+ * see:
+ * [[http://www.w3.org/TR/DOM-Level-1/level-one-core.html#ID-FF21A306]]
*/
public class CharacterData : BackedNode {
/**
diff --git a/gxml/Comment.vala b/gxml/Comment.vala
index 7dedb59..3b4901b 100644
--- a/gxml/Comment.vala
+++ b/gxml/Comment.vala
@@ -4,11 +4,13 @@
/**
* An XML comment.
*
+ * To create one, use { link GXml.Document.create_comment}.
+ *
* An XML example looks like: {{{
- * <someNode>
+ * <someNode>
* <!-- this is a comment -->
* text in the node
- * </someNode> }}}
+ * </someNode> }}}
* For more, see: [[http://www.w3.org/TR/DOM-Level-1/level-one-core.html#ID-1728279322]]
*/
public class GXml.Comment : GXml.CharacterData {
diff --git a/gxml/Document.vala b/gxml/Document.vala
index cd4c3e3..f4fa515 100644
--- a/gxml/Document.vala
+++ b/gxml/Document.vala
@@ -409,7 +409,7 @@ namespace GXml {
/* Public Methods */
/**
* Creates an empty Element node with the tag name
- * tag_name. XML example: {{{<Person></Person>}}}
+ * tag_name. XML example: {{{<Person></Person>}}}
*/
public Element create_element (string tag_name) throws DomError {
/* TODO: libxml2 doesn't complain about invalid names, but the spec
@@ -432,13 +432,13 @@ namespace GXml {
/**
* Creates a text node containing the text in data.
* XML example:
- * {{{<someElement>Text is contained here.</someElement>}}}
+ * {{{<someElement>Text is contained here.</someElement>}}}
*/
public Text create_text_node (string data) {
return new Text (this.xmldoc->new_text (data), this);
}
/**
- * Creates an XML comment with data. XML example: {{{<!-- data -->}}}
+ * Creates an XML comment with data. XML example: {{{<!-- data -->}}}
*/
public Comment create_comment (string data) {
return new Comment (this.xmldoc->new_comment (data), this);
@@ -447,7 +447,7 @@ namespace GXml {
/**
* Creates a CDATA section containing data. XML
* example:
- * {{{ <![CDATA[Here contains non-XML data, like
+ * {{{ <![CDATA[Here contains non-XML data, like
* code, or something that requires a lot of special
* XML entities.]]>. }}}
*/
@@ -459,8 +459,8 @@ namespace GXml {
}
/**
* Creates a Processing Instructions. XML example:
- * {{{<?pi_target processing instruction data?>
- * <?xml-stylesheet href="style.xsl" type="text/xml"?>}}}
+ * {{{<?pi_target processing instruction data?>
+ * <?xml-stylesheet href="style.xsl" type="text/xml"?>}}}
*/
public ProcessingInstruction create_processing_instruction (string target, string data) throws DomError {
check_html ("processing instructions"); // TODO: i18n
diff --git a/gxml/DocumentFragment.vala b/gxml/DocumentFragment.vala
index 28f309c..cf68045 100644
--- a/gxml/DocumentFragment.vala
+++ b/gxml/DocumentFragment.vala
@@ -15,13 +15,17 @@ namespace GXml {
*/
/**
- * An incomplete portion of a Document. This is not restricted
- * to having a root document element, or being completely
- * valid. It can have multiple children, which, if the
- * DocumentFragment is inserted as a child to another node,
- * become that nodes' children, without the DocumentFragment
- * itself existing as a child.
- * For more, see: [[http://www.w3.org/TR/DOM-Level-1/level-one-core.html#ID-B63ED1A3]]
+ * An partial portion of a { link GXml.Document}, not necessarily valid XML.
+ *
+ * To create one, use { link GXml.Document.create_document_fragment}.
+ *
+ * This does not need to have a root document element,
+ * or being completely valid. It can have multiple children,
+ * which, if the DocumentFragment is inserted as a child to
+ * another node, become that nodes' children, without the
+ * DocumentFragment itself existing as a child. For more,
+ * see:
+ * [[http://www.w3.org/TR/DOM-Level-1/level-one-core.html#ID-B63ED1A3]]
*/
public class DocumentFragment : BackedNode {
internal DocumentFragment (Xml.Node *fragment_node, Document doc) {
diff --git a/gxml/DocumentType.vala b/gxml/DocumentType.vala
index e9e595d..b4d2e69 100644
--- a/gxml/DocumentType.vala
+++ b/gxml/DocumentType.vala
@@ -2,6 +2,7 @@
namespace GXml {
/**
* Defines a Document, such as the entities that it can use.
+ *
* For more, see: [[http://www.w3.org/TR/DOM-Level-1/level-one-core.html#ID-412266927]]
*/
public class DocumentType : DomNode {
diff --git a/gxml/DomNode.vala b/gxml/DomNode.vala
index ef1a4a2..ee2403c 100644
--- a/gxml/DomNode.vala
+++ b/gxml/DomNode.vala
@@ -3,8 +3,12 @@ namespace GXml {
/* TODO: consider adding public signals for new/deleted children */
/**
- * 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]]
+ * Represents an XML Node, the base class for most XML structures in
+ * the { link GXml.Document}'s tree.
+ *
+ * { link GXml.Document}s are { link GXml.DomNode}s, and are
+ * composed of a tree of { link GXml.DomNode}s. See
+ * [[http://www.w3.org/TR/DOM-Level-1/level-one-core.html#ID-1950641247]]
*/
public class DomNode : GLib.Object {
internal DomNode (NodeType type, Document owner) {
@@ -151,11 +155,12 @@ namespace GXml {
* 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
+ * The { link GXml.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
+ * already-active { link GXml.NodeList}.
+ */
+ /*
+ * @todo: list nodes that use children for values
*/
public virtual NodeList? child_nodes {
// TODO: need to implement NodeList
@@ -210,15 +215,15 @@ namespace GXml {
// These may need to be overridden by subclasses that support them.
// TODO: figure out what non-BackedNode classes should be doing with these, anyway
+ // #todo: want to throw other relevant errors
/**
* 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.
+ * Throws { link GXml.DomError.NOT_FOUND} if ref_child is not a valid child.
*/
- // #todo: want to throw other relevant errors
public virtual DomNode? insert_before (DomNode new_child, DomNode? ref_child) throws DomError {
return null;
}
diff --git a/gxml/Element.vala b/gxml/Element.vala
index 48de838..3a333f9 100644
--- a/gxml/Element.vala
+++ b/gxml/Element.vala
@@ -3,7 +3,11 @@ namespace GXml {
// TODO: figure out how to create this; Xml.Doc doesn't have new_element()
/**
- * Represent an XML Element node. These can have child nodes
+ * Represent an XML Element node, which have attributes and children.
+ *
+ * To create one, use { link GXml.Document.create_element}.
+ *
+ * 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 DomNode,
@@ -19,10 +23,10 @@ namespace GXml {
/**
* The element's tag_name. Multiple elements can have
* the same tag name in a document. XML example:
- * {{{<photos>
- * <img src="..." />
- * <img src="..." />
- * </photos>}}}
+ * {{{<photos>
+ * <img src="..." />
+ * <img src="..." />
+ * </photos>}}}
* In this example, photos and img are tag names.
*/
public string tag_name {
@@ -453,14 +457,14 @@ namespace GXml {
// /**
// * This is a convenience method for Elements, mostly
// * useful when you know a given element's children are
- // * only Text. With the example {{{<shops><shop
- // * id="1">Eeylops Owl Emporium</shop><shop
- // * id="2">Obscurus Books</shop></shops>}}} taking the
+ // * only Text. With the example {{{<shops><shop
+ // * id="1">Eeylops Owl Emporium</shop><shop
+ // * id="2">Obscurus Books</shop></shops>}}} taking the
// * node for the shop element with id 1 and using this
// * method, you would get back "Eeylops Owl Emporiums".
// * If you used it on the shops element, you'd get
- // * '<shop id="1">Eeylops Owl Emporium</shop><shop
- // * id="2">Obscurus Books</shop>'
+ // * {{{<shop id="1">Eeylops Owl Emporium</shop><shop
+ // * id="2">Obscurus Books</shop>}}}
// *
// * @return XML string of child contents
// */
@@ -471,14 +475,14 @@ namespace GXml {
/**
* This is a convenience property for Elements, mostly
* useful when you know a given element's children are
- * only Text. With the example {{{<shops><shop
- * id="1">Eeylops Owl Emporium</shop><shop
- * id="2">Obscurus Books</shop></shops>}}} taking the
+ * only Text. With the example {{{<shops><shop
+ * id="1">Eeylops Owl Emporium</shop><shop
+ * id="2">Obscurus Books</shop></shops>}}} taking the
* node for the shop element with id 1 and using this
* method, you would get back "Eeylops Owl Emporiums".
* If you used it on the shops element, you'd get
- * '<shop id="1">Eeylops Owl Emporium</shop><shop
- * id="2">Obscurus Books</shop>'
+ * {{{<shop id="1">Eeylops Owl Emporium</shop><shop
+ * id="2">Obscurus Books</shop>}}}
*/
// TODO: add test
public string content {
diff --git a/gxml/EntityReference.vala b/gxml/EntityReference.vala
index 27721c4..9f18b91 100644
--- a/gxml/EntityReference.vala
+++ b/gxml/EntityReference.vala
@@ -5,8 +5,13 @@ namespace GXml {
// 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 "'" for an apostrophe.
+ * A reference to an unparsed { link GXml.Entity}, like "'" for an apostrophe.
+ *
+ * To create one, use { link GXml.Document.create_entity_reference}.
+ *
+ * The entity name, e.g. "apos", is stored as the EntityReference's `node_name`.
* 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
diff --git a/gxml/Implementation.vala b/gxml/Implementation.vala
index c89983b..4ca9fc2 100644
--- a/gxml/Implementation.vala
+++ b/gxml/Implementation.vala
@@ -2,7 +2,9 @@
namespace GXml {
/**
* Describes the features available in this
- * implementation. This can be accessed from a Document
+ * implementation of the DOM.
+ *
+ * This can be accessed from a { link GXml.Document}
* object. Provided a possible feature and the feature's
* version, it can tell the client whether it is here
* implemented.
diff --git a/gxml/NamespaceAttr.vala b/gxml/NamespaceAttr.vala
index e4476b2..e1e63e2 100644
--- a/gxml/NamespaceAttr.vala
+++ b/gxml/NamespaceAttr.vala
@@ -1,7 +1,9 @@
/* -*- Mode: vala; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */
namespace GXml {
/**
- * Represents an XML Namespace Attr node. These represent
+ * Represents an XML Namespace Attr node.
+ *
+ * These represent
* prefix=uri pairs that define namespaces for XML Elements
* and Attrs.
*/
@@ -21,7 +23,7 @@ namespace GXml {
/**
* The prefix that this xmlns attribute defines. So,
- * if the element was like {{{<Fish xmlns:foods="http://fishies.org/foods"; />}}}, the
+ * if the element was like {{{<Fish xmlns:foods="http://fishies.org/foods"; />}}}, the
* defined prefix would be foods.
*/
public string defined_prefix {
@@ -34,7 +36,7 @@ namespace GXml {
/**
* The namespace uri that this xmlns attribute defines. So,
- * if the element was like {{{<Fish xmlns:foods="http://fishies.org/foods"; />}}}, the
+ * if the element was like {{{<Fish xmlns:foods="http://fishies.org/foods"; />}}}, the
* defined namespace uri would be [[http://fishies.org/foods/]].
*/
public string defined_namespace_uri {
diff --git a/gxml/NodeList.vala b/gxml/NodeList.vala
index e0c8033..4e945c6 100644
--- a/gxml/NodeList.vala
+++ b/gxml/NodeList.vala
@@ -4,8 +4,9 @@ using Gee;
namespace GXml {
/**
- * The NodeList is a live list used to store nodes, often the
- * children of a node, or a list of nodes matching a tag name.
+ * A live list used to store { link GXml.DomNode}s. Usually the
+ * children of a { link GXml.DomNode}, or the results of
+ * { link GXml.Element.get_elements_by_tag_name}.
*/
public interface NodeList : Gee.Iterable<DomNode> {
public abstract ulong length {
diff --git a/gxml/NodeType.vala b/gxml/NodeType.vala
index 638db5e..768df80 100644
--- a/gxml/NodeType.vala
+++ b/gxml/NodeType.vala
@@ -1,26 +1,26 @@
/* -*- Mode: vala; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */
-namespace GXml {
- // TODO: want a method to convert NodeType to a string
+// 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
- GLib-GObject-CRITICAL **: g_param_spec_enum: assertion `g_enum_get_value (enum_class, default_value) != NULL' failed */
- X_UNKNOWN = 0,
- ELEMENT = 1,
- ATTRIBUTE,
- TEXT,
- CDATA_SECTION,
- ENTITY_REFERENCE,
- ENTITY,
- PROCESSING_INSTRUCTION,
- COMMENT,
- DOCUMENT,
- DOCUMENT_TYPE,
- DOCUMENT_FRAGMENT,
- NOTATION;
- }
+/**
+ * Enumerates possible NodeTypes.
+ *
+ * For more, see: [[http://www.w3.org/TR/DOM-Level-1/level-one-core.html#ID-1950641247]]
+ */
+public enum GXml.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
+ GLib-GObject-CRITICAL **: g_param_spec_enum: assertion `g_enum_get_value (enum_class, default_value) != NULL' failed */
+ X_UNKNOWN = 0,
+ ELEMENT = 1,
+ ATTRIBUTE,
+ TEXT,
+ CDATA_SECTION,
+ ENTITY_REFERENCE,
+ ENTITY,
+ PROCESSING_INSTRUCTION,
+ COMMENT,
+ DOCUMENT,
+ DOCUMENT_TYPE,
+ DOCUMENT_FRAGMENT,
+ NOTATION;
}
diff --git a/gxml/Notation.vala b/gxml/Notation.vala
index cd6ca32..1c9ab0d 100644
--- a/gxml/Notation.vala
+++ b/gxml/Notation.vala
@@ -2,6 +2,8 @@
namespace GXml {
// TODO: see if we can actually support these via libxml2, I can't seem to get to them through Xml.DTD
/**
+ * Used in defining { link GXml.DocumentType}s to declare the format of { link GXml.Entity} and { link GXml.ProcessingInstruction}s.
+ *
* Used collectively in defining DocumentTypes. A Notation can
* declare the format of unparsed entities or
* ProcessingInstruction targets.
diff --git a/gxml/ProcessingInstruction.vala b/gxml/ProcessingInstruction.vala
index 5d66a5f..b003e61 100644
--- a/gxml/ProcessingInstruction.vala
+++ b/gxml/ProcessingInstruction.vala
@@ -6,10 +6,15 @@ namespace GXml {
/**
* Stores processor-specific information with the document in
- * a textual format. For example, with XML stylesheets:
- * {{{<?xml-stylesheet href="style.xsl" type="text/xml"?>}}}
+ * a textual format.
+ *
+ * To create one, use { link GXml.Document.create_processing_instruction}.
+ *
+ * For an example of a ProcessingInstruction, this one specifies a stylesheet:
+ * {{{<?xml-stylesheet href="style.xsl" type="text/xml"?>}}}
+ *
* The general form is
- * {{{<?pi_target processing instruction data?>}}}
+ * {{{<?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 : DomNode {
diff --git a/gxml/Serializable.vala b/gxml/Serializable.vala
index caab9e8..c92f9d8 100644
--- a/gxml/Serializable.vala
+++ b/gxml/Serializable.vala
@@ -31,9 +31,7 @@ using GXml;
[CCode (gir_namespace = "GXml", gir_version = "0.2")]
namespace GXml {
/**
- * Provides interface methods that a class can implement to
- * directly handle serialisation of various properties or
- * treat other data as properties.
+ * Interface allowing implementors direct control over serialisation of properties and other data
*
* A class that implements this interface will still be passed
* to { link GXml.Serialization.serialize_object} for
@@ -45,7 +43,8 @@ namespace GXml {
* approach should be used instead. Indeed, not all methods
* need to be implemented, but some accompany one another and
* should be implemented carefully, corresponding to one
- * another.
+ * another. You can also create virtual properties from
+ * non-public property fields to enable their serialization.
*
* For an example, look in tests/XmlSerializableTest
*/
diff --git a/gxml/Text.vala b/gxml/Text.vala
index 61ecf53..9bc755f 100644
--- a/gxml/Text.vala
+++ b/gxml/Text.vala
@@ -5,9 +5,11 @@ namespace GXml {
/**
* Text children of an element, not the tags or attributes.
*
+ * To create one, use { link GXml.Document.create_text_node}.
+ *
* 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>}}}
+ * 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
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
