From b4ea8f9a0602fa67c052aa1cb1902a0aa055f67f Mon Sep 17 00:00:00 2001
From: scottmk <scottmk@9efc2488-bf62-4759-914b-345cdb29e865>
Date: Mon, 15 Feb 2010 02:48:49 +0000
Subject: [PATCH 1/1] 1. Change xmlSaxAttr() to return const char* instead of
 non-const char*.

2. Add some doxygen-style comments.

3. Tidy up the white space here and there.

M    include/opensrf/xml_utils.h
M    src/libopensrf/xml_utils.c


git-svn-id: svn://svn.open-ils.org/OpenSRF/trunk@1927 9efc2488-bf62-4759-914b-345cdb29e865
---
 include/opensrf/xml_utils.h |  2 +-
 src/libopensrf/xml_utils.c  | 47 ++++++++++++++++++++++++++++++-------
 2 files changed, 40 insertions(+), 9 deletions(-)

diff --git a/include/opensrf/xml_utils.h b/include/opensrf/xml_utils.h
index ebcc15a..cbaf337 100644
--- a/include/opensrf/xml_utils.h
+++ b/include/opensrf/xml_utils.h
@@ -26,7 +26,7 @@ char* xmlDocToString(xmlDocPtr doc, int full);
 /* Takes an xmlChar** from a SAX callback and returns the value
 	for the attribute with name 'name'
 	*/
-char* xmlSaxAttr( const xmlChar** atts, const char* name ); 
+const char* xmlSaxAttr( const xmlChar** atts, const char* name ); 
 
 /**
   Sets the xml attributes from atts to the given dom node 
diff --git a/src/libopensrf/xml_utils.c b/src/libopensrf/xml_utils.c
index 2bdb4ce..d449061 100644
--- a/src/libopensrf/xml_utils.c
+++ b/src/libopensrf/xml_utils.c
@@ -3,6 +3,13 @@
 /* helper function */
 static jsonObject* _xmlToJSON(xmlNodePtr node, jsonObject*);
 
+/**
+	@brief Write then contents of an xmlNode to standard output.
+	@param node Pointer to an xmlNode
+
+	Write the text content of an xmlNode, and all its dependent nodes recursively, to
+	standard output.
+*/
 void recurse_doc( xmlNodePtr node ) {
 	if( node == NULL ) return;
 	printf("Recurse: %s =>  %s", node->name, node->content );
@@ -13,8 +20,6 @@ void recurse_doc( xmlNodePtr node ) {
 	}
 }
 
-
-
 jsonObject* xmlDocToJSON(xmlDocPtr doc) {
 	if(!doc) return NULL;
 	return _xmlToJSON(xmlDocGetRootElement(doc), NULL);
@@ -27,7 +32,7 @@ static jsonObject* _xmlToJSON(xmlNodePtr node, jsonObject* obj) {
 	if(obj == NULL) obj = jsonNewObject(NULL);
 
 	if(node->type == XML_TEXT_NODE) {
-		jsonObjectSetString(obj, (char*) node->content);	
+		jsonObjectSetString(obj, (char*) node->content);
 
 	} else if(node->type == XML_ELEMENT_NODE || node->type == XML_ATTRIBUTE_NODE ) {
 
@@ -50,7 +55,7 @@ static jsonObject* _xmlToJSON(xmlNodePtr node, jsonObject* obj) {
 		}
 
 		xmlNodePtr child = node->children;
-                if (child) { // at least one...
+		if (child) { // at least one...
 			if (child != node->last) { // more than one -- ignore TEXT nodes
 				while(child) {
 					if (child->type != XML_TEXT_NODE) _xmlToJSON(child, new_obj);
@@ -59,8 +64,8 @@ static jsonObject* _xmlToJSON(xmlNodePtr node, jsonObject* obj) {
 			} else {
 				_xmlToJSON(child, new_obj);
 			}
-                }
-	}	
+		}
+	}
 
 	return obj;
 }
@@ -92,22 +97,48 @@ char* xmlDocToString(xmlDocPtr doc, int full) {
 	}
 }
 
+/**
+	@brief Search for the value of a given attribute in an attribute array.
+	@param atts Pointer to the attribute array to be searched.
+	@param atts Pointer to the attribute name to be sought.
+	@return A pointer to the attribute value if found, or NULL if not.
 
+	The @a atts parameter points to a ragged array of strings.  The @a atts[0] pointer points
+	to an attribute name, and @a atts[1] points to the corresponding attribute value.  The
+	remaining pointers likewise point alternately to names and values.  The end of the
+	list is marked by a NULL.
 
+	In practice, the @a atts array is constructed by the XML parser and passed to a callback
+	function.
 
-char* xmlSaxAttr( const xmlChar** atts, const char* name ) {
+*/
+const char* xmlSaxAttr( const xmlChar** atts, const char* name ) {
 	if( atts && name ) {
 		int i;
 		for(i = 0; (atts[i] != NULL); i++) {
 			if(!strcmp((char*) atts[i], name)) {
-				if(atts[++i]) return (char*) atts[i];
+				if(atts[++i])
+					return (const char*) atts[i];
 			}
 		}
 	}
 	return NULL;
 }
 
+/**
+	@brief Add a series of attributes to an xmlNode.
+	@param node Pointer to the xmlNode to which the attributes will be added.
+	@param atts Pointer to the attributes to be added.
+	@return Zero in all cases.
+
+	The @a atts parameter points to a ragged array of strings.  The @a atts[0] pointer points
+	to an attribute name, and @a atts[1] points to the corresponding attribute value.  The
+	remaining pointers likewise point alternately to names and values.  The end of the
+	list is marked by a NULL.
 
+	In practice, the @a atts array is constructed by the XML parser and passed to a callback
+	function.
+*/
 int xmlAddAttrs( xmlNodePtr node, const xmlChar** atts ) {
 	if( node && atts ) {
 		int i;
-- 
2.43.2