[cvs-annodex] commit (/annodex): libannodex/trunk/src/libannodex/xtag.c libannodex/trunk/src/libannodex/xtag.h

[conrad]

Update of /annodex (new revision 797)

Modified files:
   libannodex/trunk/src/libannodex/xtag.c
   libannodex/trunk/src/libannodex/xtag.h

Log Message:
add documentation for XTag, and label this API as version 1.0 in preparation
for an API change to accomodate (ticket: 2)


Modified: libannodex/trunk/src/libannodex/xtag.c
===================================================================
--- libannodex/trunk/src/libannodex/xtag.c	2005-01-31 13:24:11 UTC (rev 796)
+++ libannodex/trunk/src/libannodex/xtag.c	2005-01-31 22:16:39 UTC (rev 797)
@@ -30,10 +30,13 @@
    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
-/*
- * xtag.c
+/**
+ * \file xtag.c
  *
- * A trivial parser for xml-like tags
+ * XTag: A trivial parser for xml-like tags.
+ *
+ * API Version: 1.0
+ * Author: Conrad Parker, 2003
  */
 
 #if HAVE_CONFIG

Modified: libannodex/trunk/src/libannodex/xtag.h
===================================================================
--- libannodex/trunk/src/libannodex/xtag.h	2005-01-31 13:24:11 UTC (rev 796)
+++ libannodex/trunk/src/libannodex/xtag.h	2005-01-31 22:16:39 UTC (rev 797)
@@ -30,6 +30,15 @@
    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
+/**
+ * \file xtag.h
+ *
+ * XTag: A trivial parser for xml-like tags.
+ *
+ * API Version: 1.0
+ * Author: Conrad Parker, 2003
+ */
+
 #ifndef __XTAG_H__
 #define __XTAG_H__
 
@@ -37,22 +46,86 @@
 extern "C" {
 #endif /* __cplusplus */
 
-typedef void XTag;
+/**
+ * An opaque object representing an XML element.
+ * XTag objects are structured recursively, each containing child elements
+ * as other XTag objects.
+ */
+typedef struct _XTag XTag;
 
+/**
+ * Instantiate a new XTag object from a memory buffer of character data.
+ * \param s The memory buffer to parse, treated as a C string.
+ * \param n The maximum number of bytes to parse.
+ * \returns A newly created XTag object
+ * \retval NULL The tag could not be parsed by XTag
+ */
 XTag * xtag_new_parse (const char * s, int n);
 
+/**
+ * Retrieve the name of an element.
+ * \param xtag An XTag object
+ * \returns The element name
+ * \retval NULL \a xtag is NULL.
+ */
 const char * xtag_get_name (XTag * xtag);
 
+/**
+ * Retrieve the parsed character data contained by an element.
+ * \param xtag An XTag object
+ * \returns The parsed character data contained by \a xtag.
+ * \retval NULL \a xtag is NULL or contains no parsed character data.
+ */
 const char * xtag_get_pcdata (XTag * xtag);
 
+/**
+ * Retrieve an explicitly named attribute from an XTag
+ * \param xtag An XTag object
+ * \param attribute The attribute to retrieve
+ * \returns The attribute value
+ * \retval NULL \a xtag is NULL, or contains no such attribute.
+ */
 const char * xtag_get_attribute (XTag * xtag, const char * attribute);
 
+/**
+ * Retrieve the first child element with an explicit name from an XTag
+ * \param xtag An XTag object
+ * \param name The name of the child to retrieve, or NULL to retrieve the
+ * first child regardless of name.
+ * \returns An XTag object representing the desired child, if found.
+ * \retval NULL \a xtag is NULL, or no such child exists.
+ */
 XTag * xtag_first_child (XTag * xtag, const char * name);
 
+/**
+ * Retrieve the next explicitly named child element from an XTag.
+ * \param xtag An XTag object
+ * \param name The name of the child to retrieve, or NULL to retrieve the
+ * next child regardless of name.
+ * \returns An XTag object representing the desired child, if found.
+ * \retval NULL \a xtag is NULL, or no such child exists.
+ */
 XTag * xtag_next_child (XTag * xtag, const char * name);
 
+/**
+ * Free an XTag object.
+ * \param xtag An XTag object
+ * \returns NULL
+ */
 XTag * xtag_free (XTag * xtag);
 
+/**
+ * Write an XTag into a memory buffer, in XML format.
+ * \param buf The memory buffer to write into.
+ * \param n The maximum number of bytes to write.
+ * \param xtag An XTag object
+ * \returns The total length in bytes of the printed XTag. This may be
+ * greater than \a n if the given buffer is not large enough to fully
+ * print \a xtag.
+ * \note The return value of xtag_snprint() conforms to C99-style snprintf()
+ * semantics on all systems. xtag_snprint() may be called with \a n = 0 to
+ * query the buffer length required to print the given XTag.
+ */
 int xtag_snprint (char * buf, int n, XTag * xtag);
 
 #ifdef __cplusplus


-- 
conrad