[gxml] gxml/*.vala: update docs, markup special values, type links, and add memory management guidance
- From: Richard Hans Schwarting <rschwart src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gxml] gxml/*.vala: update docs, markup special values, type links, and add memory management guidance
- Date: Mon, 14 Oct 2013 08:37:02 +0000 (UTC)
commit e19f60f3847af955b0a5ddb8fd7a7b6ec23083e1
Author: Richard Schwarting <aquarichy gmail com>
Date: Wed Oct 2 10:00:14 2013 -0400
gxml/*.vala: update docs, markup special values, type links, and add memory management guidance
gxml/Attr.vala | 9 +++-
gxml/BackedNode.vala | 1 +
gxml/Document.vala | 8 ++--
gxml/Element.vala | 4 +-
gxml/Entity.vala | 6 +-
gxml/Implementation.vala | 8 ++--
gxml/Node.vala | 95 +++++++++++++++++++++++++++------------------
gxml/NodeList.vala | 2 +-
gxml/Notation.vala | 4 +-
gxml/Serializable.vala | 2 +-
gxml/Serialization.vala | 2 +-
11 files changed, 82 insertions(+), 59 deletions(-)
---
diff --git a/gxml/Attr.vala b/gxml/Attr.vala
index b7a8d6d..2f087ef 100644
--- a/gxml/Attr.vala
+++ b/gxml/Attr.vala
@@ -61,14 +61,11 @@ namespace GXml {
*/
public override string? namespace_uri {
get {
- // TODO: there can be multiple NSes on a node, using ->next, right now we
just return the first. What should we do?!?!
if (this.node->ns == null) {
return null;
} else {
return this.node->ns->href;
}
- // TODO: handle null ns_def
- // TODO: figure out when node->ns is used, as opposed to ns_def
}
internal set {
}
@@ -111,8 +108,14 @@ namespace GXml {
/* Public properties (Node general) */
+ /* TODO: find out how to get these to appear in GtkDocs, since they're
+ overriding a base class. Figure out how to get that multiple lines to
+ appear in the generated valadoc */
/**
* The node_name of an attribute is the attribute's name.
+ *
+ * Do not free this. It's memory will be released
+ * when the owning { link GXml.Document} is freed.
*/
public override string node_name {
get {
diff --git a/gxml/BackedNode.vala b/gxml/BackedNode.vala
index 4fd861b..07f885d 100644
--- a/gxml/BackedNode.vala
+++ b/gxml/BackedNode.vala
@@ -72,6 +72,7 @@ namespace GXml {
*/
public override string? namespace_uri {
get {
+ // TODO: there can be multiple NSes on a node, using ->next, right now we
just return the first. What should we do?!?!
if (this.node->ns == null) {
return null;
} else {
diff --git a/gxml/Document.vala b/gxml/Document.vala
index 8d49864..71d8c35 100644
--- a/gxml/Document.vala
+++ b/gxml/Document.vala
@@ -181,7 +181,7 @@ namespace GXml {
// TODO: DTD, sort of works
/**
- * The Document Type Definition (DTD) defining this document. This may be `null`.
+ * The Document Type Definition (DTD) defining this document. This may be %NULL.
*
* Version: DOM Level 1 Core
* URL: [[http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#attribute-doctype]]
@@ -254,9 +254,9 @@ namespace GXml {
* URL: [[http://www.w3.org/TR/DOM-Level-3-Core/core.html#Level-2-Core-DOM-createDocument]]
*
* @param impl Implementation creating this Document.
- * @param namespace_uri URI for the namespace in which this Document belongs, or `null`.
- * @param qualified_name A qualified name for the Document, or `null`.
- * @param doctype The type of the document, or `null`.
+ * @param namespace_uri URI for the namespace in which this Document belongs, or %NULL.
+ * @param qualified_name A qualified name for the Document, or %NULL.
+ * @param doctype The type of the document, or %NULL.
*
* @return The new document.
*/
diff --git a/gxml/Element.vala b/gxml/Element.vala
index 2713cfe..6ae5fa7 100644
--- a/gxml/Element.vala
+++ b/gxml/Element.vala
@@ -289,7 +289,7 @@ namespace GXml {
*
* @param name The name of the Attr node to retrieve.
*
- * @return The Attr node named by name for this element, or null if none is set.
+ * @return The Attr node named by name for this element, or %NULL if none is set.
*/
public Attr? get_attribute_node (string name) {
// TODO: verify that attributes returns null with unknown name
@@ -305,7 +305,7 @@ namespace GXml {
*
* @return If an Attr with the same name exists, it
* is replaced and the old Attr is returned.
- * Elsewise, null is returned.
+ * Elsewise, %NULL is returned.
*/
public Attr set_attribute_node (Attr new_attr) {
// TODO: INUSE_ATTRIBUTE_ERR if new_attr already belongs to another element
diff --git a/gxml/Entity.vala b/gxml/Entity.vala
index 4a2f6c1..a7f3131 100644
--- a/gxml/Entity.vala
+++ b/gxml/Entity.vala
@@ -33,7 +33,7 @@ namespace GXml {
private Xml.Entity *entity;
/**
- * A public identifier for the entity. `null` when unspecified.
+ * A public identifier for the entity. %NULL when unspecified.
*/
public string public_id {
get {
@@ -44,7 +44,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 {
@@ -56,7 +56,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/Implementation.vala b/gxml/Implementation.vala
index 58323d0..795fc82 100644
--- a/gxml/Implementation.vala
+++ b/gxml/Implementation.vala
@@ -81,9 +81,9 @@ namespace GXml {
* Version: DOM Level 3 Core
* URL: [[http://www.w3.org/TR/DOM-Level-3-Core/core.html#Level-2-Core-DOM-createDocument]]
- * @param namespace_uri URI for the namespace in which this Document belongs, or `null`.
- * @param qualified_name A qualified name for the Document, or `null`.
- * @param doctype The type of the document, or `null`.
+ * @param namespace_uri URI for the namespace in which this Document belongs, or %NULL.
+ * @param qualified_name A qualified name for the Document, or %NULL.
+ * @param doctype The type of the document, or %NULL.
*
* @return The new document.
*/
@@ -107,7 +107,7 @@ namespace GXml {
* TODO: implement more of this, using libxml2's parser.h's xmlGetFeature, xmlHasFeature, etc.
*
* @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.
+ * @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.
*/
diff --git a/gxml/Node.vala b/gxml/Node.vala
index 6883996..c907ae5 100644
--- a/gxml/Node.vala
+++ b/gxml/Node.vala
@@ -175,7 +175,7 @@ namespace GXml {
* when the owning { link GXml.Document} is freed.
*
* Version: DOM Level 1 Core
- * URL: [[http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#attribute-nodeName]]
+ * URL: [[http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#ID-F68D095]]
*/
public virtual string node_name {
get; internal set;
@@ -184,13 +184,13 @@ namespace GXml {
/**
* Stores the value of the Node. The nature of
* node_value varies based on the type of node. This
- * can be null.
+ * can be %NULL.
*
* Do not free this. It's memory will be released
* when the owning { link GXml.Document} is freed.
*
* Version: DOM Level 1 Core
- * URL: [[http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#attribute-nodeValue]]
+ * URL: [[http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#ID-F68D080]]
*/
public virtual string? node_value {
get {
@@ -204,11 +204,13 @@ namespace GXml {
private NodeType _node_type;
/**
* Stores the type of node. Most XML structures are
- * nodes of different types, like Document, Attr,
- * Element, etc.
+ * nodes of different types, like { link GXml.Document}
+ * as a { link GXml.NodeType.DOCUMENT}, { link GXml.Attr}
+ * as a { link GXml.NodeType.ATTRIBUTE}, Element as a
+ * { link GXml.NodeType.ELEMENT}, etc.
*
* Version: DOM Level 1 Core
- * URL: [[http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#attribute-nodeType]]
+ * URL: [[http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#ID-111237558]]
*/
public virtual NodeType node_type {
get {
@@ -222,7 +224,7 @@ namespace GXml {
}
/**
- * A link to the parent of this node. For example,
+ * A link to the parent_node of this node. For example,
* with elements, the immediate, outer element is the parent.
*
* XML example: {{{<parent><child></child></parent>}}}
@@ -231,7 +233,7 @@ namespace GXml {
* when the owning { link GXml.Document} is freed.
*
* Version: DOM Level 1 Core
- * URL: [[http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#attribute-parentNode]]
+ * URL: [[http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#ID-1060184317]]
*/
public virtual Node? parent_node {
get { return null; }
@@ -240,9 +242,10 @@ namespace GXml {
/**
* 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.
+ * represent the value of a node as a tree of
+ * { link GXml.Node}, whereas node_value represents
+ * it as a string. This can be %NULL for node types
+ * that have no children.
*
* The { link GXml.NodeList} is live, in that changes to this
* node's children will be reflected in an
@@ -253,7 +256,7 @@ namespace GXml {
* constructed dynamically.
*
* Version: DOM Level 1 Core
- * URL: [[http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#attribute-childNodes]]
+ * URL: [[http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#ID-1451460987]]
*/
/*
* @todo: identify node types that use children for values, like attribute
@@ -266,13 +269,13 @@ namespace GXml {
/**
* Links to the first child. If there are no
- * children, it returns null.
+ * children, it returns %NULL.
*
* Do not free this. It's memory will be released
* when the owning { link GXml.Document} is freed.
*
* Version: DOM Level 1 Core
- * URL: [[http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#attribute-firstChild]]
+ * URL: [[http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#ID-169727388]]
*/
public virtual Node? first_child {
get { return null; }
@@ -281,13 +284,13 @@ namespace GXml {
/**
* Links to the last child. If there are no
- * children, it returns null.
+ * children, it returns %NULL.
*
* Do not free this. It's memory will be released
* when the owning { link GXml.Document} is freed.
*
* Version: DOM Level 1 Core
- * URL: [[http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#attribute-lastChild]]
+ * URL: [[http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#ID-61AD09FB]]
*/
public virtual Node? last_child {
get { return null; }
@@ -296,14 +299,14 @@ namespace GXml {
/**
* Links to this node's preceding sibling. If there
- * are no previous siblings, it returns null. Note
+ * are no previous siblings, it returns %NULL. Note
* that the children of a node are ordered.
*
* Do not free this. It's memory will be released
* when the owning { link GXml.Document} is freed.
*
* Version: DOM Level 1 Core
- * URL: [[http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#attribute-previousSibling]]
+ * URL: [[http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#ID-640FB3C8]]
*/
public virtual Node? previous_sibling {
get { return null; }
@@ -312,14 +315,14 @@ namespace GXml {
/**
* Links to this node's next sibling. If there is no
- * next sibling, it returns null. Note that the
+ * next sibling, it returns %NULL. Note that the
* children of a node are ordered.
*
* Do not free this. It's memory will be released
* when the owning { link GXml.Document} is freed.
*
* Version: DOM Level 1 Core
- * URL: [[http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#attribute-nextSibling]]
+ * URL: [[http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#ID-6AC54C2F]]
*/
public virtual Node? next_sibling {
get { return null; }
@@ -337,7 +340,7 @@ namespace GXml {
* when the owning { link GXml.Document} is freed.
*
* Version: DOM Level 1 Core
- * URL: [[http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#attribute-attributes]]
+ * URL: [[http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#ID-84CF09]]
*/
public virtual HashTable<string,Attr>? attributes {
get { return null; }
@@ -352,7 +355,7 @@ namespace GXml {
* { link GXml.Node}.
*
* Version: DOM Level 1 Core
- * URL: [[http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#attribute-ownerDocument]]
+ * URL: [[http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#node-ownerDoc]]
*/
public weak Document owner_document {
get;
@@ -366,16 +369,19 @@ namespace GXml {
* @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`.
+ * Insert { link new_child} as a child to this node, and place
+ * it in the list before { link ref_child}.
*
- * If `ref_child` is `null`, `new_child` is appended to the
+ * If { link ref_child} is %NULL, { link new_child} is appended to the
* list of children instead.
*
* Version: DOM Level 1 Core
* URL: [[http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#method-insertBefore]]
*
- * @return `new_child`, the node that has been
+ * @param new_child A new { link GXml.Node} that will become a child of the current one
+ * @param ref_child The child that { link new_child} will be placed ahead of
+ *
+ * @return { link new_child}, the node that has been
* inserted. Do not free it, its memory will be
* released when the owning { link GXml.Document} is
* freed.
@@ -385,12 +391,15 @@ namespace GXml {
}
/**
- * Replaces `old_child` with `new_child` in this node's list of children.
+ * Replaces { link old_child} with { link new_child} in this node's list of children.
*
* Version: DOM Level 1 Core
* URL: [[http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#method-replaceChild]]
*
- * @return The removed node `old_child`. Do not free it, its memory will be
+ * @param new_child A new { link GXml.Node} that will become a child of the current one
+ * @param old_child A { link GXml.Node} that will be removed and replaced by { link new_child}
+ *
+ * @return The removed node { link old_child}. Do not free it, its memory will be
* released when the owning { link GXml.Document} is
* freed.
*/
@@ -399,26 +408,34 @@ namespace GXml {
}
/**
- * Removes `old_child` from this node's list of children.
+ * Removes { link old_child} from this node's list of children,
+ * { link GXml.Node.child_nodes}.
*
* Version: DOM Level 1 Core
* URL: [[http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#method-removeChild]]
*
- * @return The removed node `old_child`. Do not free it, its memory will be
+ * @param old_child The { link GXml.Node} child to remove from the current one
+ *
+ * @return The removed node { link old_child}. Do not free it, its memory will be
* released when the owning { link GXml.Document} is
- * freed.
+ * freed
*/
public virtual unowned Node? remove_child (Node old_child) {
return null;
}
/**
- * Appends `new_child` to the end of this node's list of children.
+ * Appends { link new_child} to the end of this node's list of children,
+ * { link GXml.Node.child_nodes}.
*
* Version: DOM Level 1 Core
+ *
* URL: [[http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#method-appendChild]]
*
- * @return The newly added child. Do not free it, its memory will be
+ * @param new_child A new { link GXml.Node} that will
+ * become the last child of this current node
+ *
+ * @return The newly added child, { link new_child}. Do not free it, its memory will be
* released when the owning { link GXml.Document} is
* freed.
*/
@@ -430,9 +447,10 @@ namespace GXml {
* Indicates whether this node has children.
*
* Version: DOM Level 1 Core
+ *
* URL: [[http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#method-hasChildNodes]]
*
- * @return `true` if this node has children, `false` if not
+ * @return %TRUE if this node has children, %FALSE if not
*/
public virtual bool has_child_nodes () {
return false;
@@ -442,9 +460,10 @@ namespace GXml {
* Creates a parentless copy of this node.
*
* Version: DOM Level 1 Core
+ *
* URL: [[http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#method-cloneNode]]
*
- * @param deep If `true`, descendants are cloned as well. If `false`, they are not.
+ * @param deep If %TRUE, descendants are cloned as well. If %FALSE, they are not.
*
* @return A parentless clone of this node. Do not
* free it, its memory will be released when the owning
@@ -461,12 +480,12 @@ namespace GXml {
* CDATA section, or an EntityRef, it will not be
* formatted, since the current implementation with
* libxml2 will not handle that case. (See libxml2's
- * xmlNodeDumpOutputInternal to understand more.)
+ * xmlNodeDumpOutput internals to understand more.)
*
- * @param format false: no formatting, true: formatted, with indentation.
+ * @param format %FALSE: no formatting, %TRUE: formatted, with indentation.
* @param level Indentation level
*
- * @return XML string for node. The caller must free
+ * @return XML string for node, which must be free
* this.
*/
// TODO: ask Colin Walters about storing docs in GIR files (might have not been him)
diff --git a/gxml/NodeList.vala b/gxml/NodeList.vala
index 39abf97..322dbdd 100644
--- a/gxml/NodeList.vala
+++ b/gxml/NodeList.vala
@@ -734,7 +734,7 @@ namespace GXml {
/**
* Obtain the current Node in the iteration.
- * Returns null if there is none, which occurs
+ * Returns %NULL if there is none, which occurs
* if the list is empty or if iteration has
* not started (next () has never been
* called).
diff --git a/gxml/Notation.vala b/gxml/Notation.vala
index c96ee48..8697028 100644
--- a/gxml/Notation.vala
+++ b/gxml/Notation.vala
@@ -47,7 +47,7 @@ namespace GXml {
}
}
/**
- * The public identifier for the notation, or null if not set.
+ * The public identifier for the notation, or %NULL if not set.
*/
public string? public_id {
get {
@@ -57,7 +57,7 @@ namespace GXml {
}
}
/**
- * The system identifier for the notation, or null if not set.
+ * The system identifier for the notation, or %NULL if not set.
*/
public string? system_id {
get {
diff --git a/gxml/Serializable.vala b/gxml/Serializable.vala
index 53ac7fc..83712f2 100644
--- a/gxml/Serializable.vala
+++ b/gxml/Serializable.vala
@@ -124,7 +124,7 @@ namespace GXml {
* @param property_name string name of a property to serialize.
* @param spec the { link GLib.ParamSpec} describing the property.
* @param doc the { link GXml.Document} the returned { link GXml.Node} should belong to
- * @return a new { link GXml.Node}, or `null`
+ * @return a new { link GXml.Node}, or %NULL
*/
/*
* @todo: consider not giving property_name, let them get name from spec?
diff --git a/gxml/Serialization.vala b/gxml/Serialization.vala
index e166a03..24b32b3 100644
--- a/gxml/Serialization.vala
+++ b/gxml/Serialization.vala
@@ -385,7 +385,7 @@ namespace GXml {
* to the system deserializing them or a
* { link GXml.SerializationError} will result.
*
- * @param node { link GXml.Node} representing a { link GLib.Object}
+ * @param doc { link GXml.Document} representing a { link GLib.Object}
* @return the deserialized { link GLib.Object}
*/
public static GLib.Object deserialize_object (GXml.Document doc) throws SerializationError {
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
