[gxml] gxml/{Element,Node}.vala: add documentation for memory usage
- From: Richard Hans Schwarting <rschwart src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gxml] gxml/{Element,Node}.vala: add documentation for memory usage
- Date: Sun, 29 Sep 2013 06:04:00 +0000 (UTC)
commit 43d70a0673d7dc4012998e617ee5f4a8baf1716f
Author: Richard Schwarting <aquarichy gmail com>
Date: Sun Sep 29 02:00:40 2013 -0400
gxml/{Element,Node}.vala: add documentation for memory usage
gxml/Element.vala | 18 +++++++++----
gxml/Node.vala | 69 +++++++++++++++++++++++++++++++++++++++++++++++-----
2 files changed, 74 insertions(+), 13 deletions(-)
---
diff --git a/gxml/Element.vala b/gxml/Element.vala
index e7db39d..2713cfe 100644
--- a/gxml/Element.vala
+++ b/gxml/Element.vala
@@ -86,12 +86,18 @@ namespace GXml {
private HashTable<string,Attr> _attributes = null;
/**
- * Contains a HashTable of Attr attributes associated with this element.
+ * Contains a { link GLib.HashTable} of
+ * { link GXml.Attr} attributes associated with this
+ * { link GXml.Element}.
*
* Attributes in the HashTable are updated live, so
* changes in the element's attributes through its
* other methods are reflected in the attributes
- * HashTable.
+ * { link GLib.HashTable}.
+ *
+ * Do not free this or its contents. It's memory will
+ * be released when the owning { link GXml.Document}
+ * is freed.
*/
public override HashTable<string,Attr>? attributes {
/*
@@ -139,10 +145,10 @@ namespace GXml {
}
/**
- * This should be called before saving a GXml Document
- * to a libxml2 Xml.Doc*, or else any changes made to
- * attributes in the Element will only exist within
- * the hash table proxy and will not be recorded.
+ * This should be called before saving a { link GXml.Document}
+ * to a { link Xml.Doc}*, or else any changes made to
+ * attributes in the { link GXml.Element} will only exist within
+ * the { link GLib.HashTable} proxy and will not be recorded.
*/
internal void save_attributes (Xml.Node *tmp_node) {
Attr attr;
diff --git a/gxml/Node.vala b/gxml/Node.vala
index 9123661..ab92961 100644
--- a/gxml/Node.vala
+++ b/gxml/Node.vala
@@ -96,6 +96,8 @@ namespace GXml {
/**
* The list of attributes that store namespace definitions. This is not part of a DOM spec.
+ *
+ * The caller must free this using { link GLib.Object.unref}.
*/
/* @TODO: determine best API for exposing these, as it's not defined in the IDL */
public virtual NodeList? namespace_definitions {
@@ -112,6 +114,9 @@ namespace GXml {
* Level 2 Core that were created with namespace
* support.
*
+ * Do not free this. It's memory will be released
+ * when the owning { link GXml.Document} is freed.
+ *
* Version: DOM Level 2 Core
* URL: [[http://www.w3.org/TR/DOM-Level-2-Core/core.html#ID-NodeNSname]]
*/
@@ -128,6 +133,9 @@ namespace GXml {
* only applies to Elements and Attrs from DOM Level 2
* Core that were created with namespace support.
*
+ * Do not free this. It's memory will be released
+ * when the owning { link GXml.Document} is freed.
+ *
* Version: DOM Level 2 Core
* URL: [[http://www.w3.org/TR/DOM-Level-2-Core/core.html#ID-NodeNSPrefix]]
*/
@@ -144,6 +152,9 @@ namespace GXml {
* only applies to Elements and Attrs from DOM Level 2
* Core that were created with namespace support.
*
+ * Do not free this. It's memory will be released
+ * when the owning { link GXml.Document} is freed.
+ *
* Version: DOM Level 2 Core
* URL: [[http://www.w3.org/TR/DOM-Level-2-Core/core.html#ID-NodeNSLocalN]]
*/
@@ -160,6 +171,9 @@ namespace GXml {
* similar to the node type, but sometimes, it is
* arbitrary.
*
+ * 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-nodeName]]
*/
@@ -172,6 +186,9 @@ namespace GXml {
* node_value varies based on the type of node. This
* 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]]
*/
@@ -210,6 +227,9 @@ namespace GXml {
*
* Example: {{{<parent><child></child></parent>}}}
*
+ * 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-parentNode]]
*/
@@ -228,6 +248,10 @@ namespace GXml {
* node's children will be reflected in an
* already-active { link GXml.NodeList}.
*
+ * The caller must call { link GLib.Object.unref} on
+ * the list when it is done with it. The lists are
+ * constructed dynamically.
+ *
* Version: DOM Level 1 Core
* URL: [[http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#attribute-childNodes]]
*/
@@ -244,6 +268,9 @@ namespace GXml {
* Links to the first child. If there are no
* 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]]
*/
@@ -256,6 +283,9 @@ namespace GXml {
* Links to the last child. If there are no
* 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]]
*/
@@ -269,6 +299,9 @@ namespace GXml {
* 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]]
*/
@@ -282,6 +315,9 @@ namespace GXml {
* 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]]
*/
@@ -295,7 +331,10 @@ namespace GXml {
* attributes for this node. `attributes`
* actually only apply to { link GXml.Element}
* nodes. For all other { link GXml.Node} subclasses,
- * `attributes` is null.
+ * `attributes` is %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-attributes]]
@@ -308,6 +347,10 @@ namespace GXml {
/**
* A link to the { link GXml.Document} to which this node belongs.
*
+ * Do not free this unless you intend to free all
+ * memory owned by the { link GXml.Document}, including this
+ * { link GXml.Node}.
+ *
* Version: DOM Level 1 Core
* URL: [[http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#attribute-ownerDocument]]
*/
@@ -332,7 +375,10 @@ namespace GXml {
* 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 inserted
+ * @return `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.
*/
public virtual unowned Node? insert_before (Node new_child, Node? ref_child) {
return null;
@@ -344,7 +390,9 @@ namespace GXml {
* 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`.
+ * @return The removed node `old_child`. Do not free it, its memory will be
+ * released when the owning { link GXml.Document} is
+ * freed.
*/
public virtual unowned Node? replace_child (Node new_child, Node old_child) {
return null;
@@ -356,7 +404,9 @@ namespace GXml {
* 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`.
+ * @return The removed node `old_child`. Do not free it, its memory will be
+ * released when the owning { link GXml.Document} is
+ * freed.
*/
public virtual unowned Node? remove_child (Node old_child) {
return null;
@@ -368,7 +418,9 @@ namespace GXml {
* 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.
+ * @return The newly added child. Do not free it, its memory will be
+ * released when the owning { link GXml.Document} is
+ * freed.
*/
public virtual unowned Node? append_child (Node new_child) {
return null;
@@ -394,7 +446,9 @@ namespace GXml {
*
* @param deep If `true`, descendants are cloned as well. If `false`, they are not.
*
- * @return A parentless clone of this node.
+ * @return A parentless clone of this node. Do not
+ * free it, its memory will be released when the owning
+ * { link GXml.Document} is freed.
*/
public virtual unowned Node? clone_node (bool deep) {
return null;
@@ -412,7 +466,8 @@ namespace GXml {
* @param format false: no formatting, true: formatted, with indentation.
* @param level Indentation level
*
- * @return XML string for node, which must be freed.
+ * @return XML string for node. The caller must free
+ * this.
*/
// TODO: ask Colin Walters about storing docs in GIR files (might have not been him)
public virtual string to_string (bool format = false, int level = 0) {
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
