From 0c1a27ee9988a9fa5b66e0f1a1e3d682942f67a4 Mon Sep 17 00:00:00 2001
From: Kalle Olavi Niemitalo <kon@iki.fi>
Date: Sat, 4 Apr 2009 22:38:56 +0300
Subject: [PATCH] Bug 1071: Document get_dom_node_value return values

---
 src/dom/node.h | 24 ++++++++++++++++++++++--
 1 file changed, 22 insertions(+), 2 deletions(-)

diff --git a/src/dom/node.h b/src/dom/node.h
index 5ab492df7..90dc3f739 100644
--- a/src/dom/node.h
+++ b/src/dom/node.h
@@ -408,8 +408,28 @@ struct dom_string *get_dom_node_value(struct dom_node *node);
 /* Returns the name used for identifying the node type. */
 struct dom_string *get_dom_node_type_name(enum dom_node_type type);
 
-/* Based on the type of the parent and the node type return a proper list
- * or NULL. This is useful when adding a node to a parent node. */
+/** Based on the type of the @a parent and the node @a type return a
+ * proper list or NULL. This is useful when adding a node to a parent
+ * node.
+ *
+ * With a <code>struct dom_node_list **list</code> returned by this
+ * function, there are four possibilities:
+ *
+ * - <code>list == NULL</code>.  This means @a parent does not support
+ *   child nodes of the given @a type.
+ *
+ * - <code>*list == NULL</code>.  This means @a parent does not yet
+ *   have any child nodes of the given @a type and so no list has been
+ *   allocated for them.  Callers should treat the lack of a list in
+ *   the same way as an empty list.
+ *
+ * - <code>(*list)->size == 0</code>.  This is an empty list.  It is
+ *   unspecified whether the DOM code keeps such lists; it could
+ *   instead change them back to NULL.
+ *
+ * - <code>(*list)->size != 0</code>.  This is a nonempty list.
+ *   However, the nodes in it might not actually be of the given
+ *   @a type because some lists are used for multiple types.  */
 static inline struct dom_node_list **
 get_dom_node_list_by_type(struct dom_node *parent, enum dom_node_type type)
 {