changeset 10327:d88ee1d73a93

[gaim-migrate @ 11534] Doxumentation from Gary. Thanks mon ami! committer: Tailor Script <[e-mail]>

--- a/src/xmlnode.h	Tue Dec 07 23:25:15 2004 +0000
+++ b/src/xmlnode.h	Wed Dec 08 00:20:38 2004 +0000
@@ -1,5 +1,6 @@
 /**
  * @file xmlnode.h XML DOM functions
+ * @ingroup core
  *
  * gaim
  *
@@ -24,40 +25,177 @@
 #ifndef _GAIM_XMLNODE_H_
 #define _GAIM_XMLNODE_H_
 
+/**
+ * The valid types for an xmlnode
+ */
 typedef enum _XMLNodeType
 {
-	XMLNODE_TYPE_TAG,
-	XMLNODE_TYPE_ATTRIB,
-	XMLNODE_TYPE_DATA
+	XMLNODE_TYPE_TAG,		/**< Just a tag */
+	XMLNODE_TYPE_ATTRIB,	/**< Has attributes */
+	XMLNODE_TYPE_DATA		/**< Has data */
 } XMLNodeType;
 
+/**
+ * An xmlnode.
+ */
 typedef struct _xmlnode
 {
-	char *name;
-	XMLNodeType type;
-	char *data;
-	size_t data_sz;
-	struct _xmlnode *parent;
-	struct _xmlnode *child;
-	struct _xmlnode *next;
+	char *name;					/**< The name of the node. */
+	XMLNodeType type;			/**< The type of the node. */
+	char *data;					/**< The data for the node. */
+	size_t data_sz;				/**< The size of the data. */
+	struct _xmlnode *parent;	/**< The parent node or @c NULL.*/
+	struct _xmlnode *child;		/**< The child node or @c NULL.*/
+	struct _xmlnode *next;		/**< The next node or @c NULL. */
 } xmlnode;
 
+/**
+ * Creates a new xmlnode.
+ *
+ * @param name The name of the node.
+ *
+ * @return The new node.
+ */
 xmlnode *xmlnode_new(const char *name);
+
+/**
+ * Creates a new xmlnode child.
+ *
+ * @param parent The parent node.
+ * @param name   The name of the child node.
+ *
+ * @return The new child node.
+ */
 xmlnode *xmlnode_new_child(xmlnode *parent, const char *name);
+
+/**
+ * Inserts a node into a node as a child.
+ *
+ * @param parent The parent node to insert child into.
+ * @param child  The child node to insert into parent.
+ */
 void xmlnode_insert_child(xmlnode *parent, xmlnode *child);
+
+/**
+ * Gets a child node named name.
+ *
+ * @param parent The parent node.
+ * @param name   The child's name.
+ *
+ * @return The child or NULL.
+ */
 xmlnode *xmlnode_get_child(xmlnode *parent, const char *name);
+
+/**
+ * Gets a child node named name in a namespace.
+ *
+ * @param parent The parent node.
+ * @param name   The child's name.
+ * @param xmlns  The namespace.
+ *
+ * @return The child or NULL.
+ */
 xmlnode *xmlnode_get_child_with_namespace(xmlnode *parent, const char *name, const char *xmlns);
+
+/**
+ * Gets the next node with the same name as node.
+ *
+ * @param node The node of a twin to find.
+ *
+ * @return The twin of node or NULL.
+ */
 xmlnode *xmlnode_get_next_twin(xmlnode *node);
+
+/**
+ * Inserts data into a node.
+ *
+ * @param parent The node to insert data into.
+ * @param data   The data to insert.
+ * @param size   The size of the data to insert.
+ */
 void xmlnode_insert_data(xmlnode *parent, const char *data, size_t size);
+
+/**
+ * Gets data from a node.
+ *
+ * @param node The node to get data from.
+ *
+ * @return The data from the node.
+ */
 char *xmlnode_get_data(xmlnode *node);
+
+/**
+ * Sets an attribute for a node.
+ *
+ * @param node  The node to set an attribute for.
+ * @param attr  The name of the attribute.
+ * @param value The value of the attribute.
+ */
 void xmlnode_set_attrib(xmlnode *node, const char *attr, const char *value);
+
+/**
+ * Gets an attribute from a node.
+ *
+ * @param node The node to get an attribute from.
+ * @param attr The attribute to get.
+ *
+ * @return The value of the attribute.
+ */
 const char *xmlnode_get_attrib(xmlnode *node, const char *attr);
+
+/**
+ * Removes an attribute from a node.
+ *
+ * @param node The node to remove an attribute from.
+ * @param attr The attribute to remove.
+ */
 void xmlnode_remove_attrib(xmlnode *node, const char *attr);
+
+/**
+ * Returns the node in a string of xml.
+ *
+ * @param node The starting node to output.
+ * @param len  Address for the size of the string.
+ *
+ * @return The node repersented as a string.
+ */
 char *xmlnode_to_str(xmlnode *node, int *len);
+
+/**
+ * Returns the node in a string of human readable xml.
+ *
+ * @param node The starting node to output.
+ * @param len  Address for the size of the string.
+ *
+ * @return The node as human readable string including
+ *          tab and new line characters.
+ */
 char *xmlnode_to_formatted_str(xmlnode *node, int *len);
+
+/**
+ * Creates a node from a string of xml.
+ *
+ * @param str  The string of xml.
+ * @param size The size of the string.
+ *
+ * @return The new node.
+ */
 xmlnode *xmlnode_from_str(const char *str, size_t size);
+
+/**
+ * Creates a new node from the source node.
+ *
+ * @param src The node to copy.
+ *
+ * @return A new copy of the src node.
+ */
 xmlnode *xmlnode_copy(xmlnode *src);
 
+/**
+ * Frees a node and all of it's children.
+ *
+ * @param node The node to free.
+ */
 void xmlnode_free(xmlnode *node);
 
 #endif /* _GAIM_XMLNODE_H_ */