Commit bcc99b15 authored by Michael R Sweet's avatar Michael R Sweet

Fix some more documentation generator bugs.

Add detailed docos to the file.
parent 0cc4b9e6
This diff is collapsed.
/*
* "$Id: mxml-attr.c,v 1.1 2003/06/03 19:46:30 mike Exp $"
* "$Id: mxml-attr.c,v 1.2 2003/06/14 23:56:47 mike Exp $"
*
* Attribute support code for mini-XML, a small XML-like file parsing library.
*
......@@ -30,6 +30,9 @@
/*
* 'mxmlElementGetAttr()' - Get an attribute.
*
* This function returns NULL if the node is not an element or the
* named attribute does not exist.
*/
const char * /* O - Attribute value or NULL */
......@@ -67,6 +70,11 @@ mxmlElementGetAttr(mxml_node_t *node, /* I - Element node */
/*
* 'mxmlElementSetAttr()' - Set an attribute.
*
* If the named attribute already exists, the value of the attribute
* is replaced by the new string value. The string value is copied
* into the element node. This function does nothing if the node is
* not an element.
*/
void
......@@ -147,5 +155,5 @@ mxmlElementSetAttr(mxml_node_t *node, /* I - Element node */
/*
* End of "$Id: mxml-attr.c,v 1.1 2003/06/03 19:46:30 mike Exp $".
* End of "$Id: mxml-attr.c,v 1.2 2003/06/14 23:56:47 mike Exp $".
*/
/*
* "$Id: mxml-file.c,v 1.9 2003/06/04 23:20:31 mike Exp $"
* "$Id: mxml-file.c,v 1.10 2003/06/14 23:56:47 mike Exp $"
*
* File loading code for mini-XML, a small XML-like file parsing library.
*
......@@ -46,13 +46,20 @@ static int mxml_write_ws(mxml_node_t *node, FILE *fp,
/*
* 'mxmlLoadFile()' - Load a file into an XML node tree.
*
* The nodes in the specified file are added to the specified top node.
* If no top node is provided, the XML file MUST be well-formed with a
* single parent node like <?xml> for the entire file. The callback
* function returns the value type that should be used for child nodes.
* If MXML_NO_CALLBACK is specified then all child nodes will be either
* MXML_ELEMENT or MXML_TEXT nodes.
*/
mxml_node_t * /* O - First node */
mxml_node_t * /* O - First node or NULL if the file could not be read. */
mxmlLoadFile(mxml_node_t *top, /* I - Top node */
FILE *fp, /* I - File to read from */
mxml_type_t (*cb)(mxml_node_t *))
/* I - Callback function */
/* I - Callback function or MXML_NO_CALLBACK */
{
mxml_node_t *node, /* Current node */
*parent; /* Current parent node */
......@@ -509,13 +516,19 @@ mxmlLoadFile(mxml_node_t *top, /* I - Top node */
/*
* 'mxmlSaveFile()' - Save an XML tree to a file.
*
* The callback argument specifies a function that returns a whitespace
* character or nul (0) before and after each element. If MXML_NO_CALLBACK
* is specified, whitespace will only be added before MXML_TEXT nodes
* with leading whitespace and before attribute names inside opening
* element tags.
*/
int /* O - 0 on success, -1 on error */
int /* O - 0 on success, -1 on error. */
mxmlSaveFile(mxml_node_t *node, /* I - Node to write */
FILE *fp, /* I - File to write to */
int (*cb)(mxml_node_t *, int))
/* I - Whitespace callback */
/* I - Whitespace callback or MXML_NO_CALLBACK */
{
int col; /* Final column */
......@@ -999,5 +1012,5 @@ mxml_write_ws(mxml_node_t *node, /* I - Current node */
/*
* End of "$Id: mxml-file.c,v 1.9 2003/06/04 23:20:31 mike Exp $".
* End of "$Id: mxml-file.c,v 1.10 2003/06/14 23:56:47 mike Exp $".
*/
/*
* "$Id: mxml-node.c,v 1.4 2003/06/05 03:06:20 mike Exp $"
* "$Id: mxml-node.c,v 1.5 2003/06/14 23:56:47 mike Exp $"
*
* Node support code for mini-XML, a small XML-like file parsing library.
*
......@@ -44,12 +44,19 @@ static mxml_node_t *mxml_new(mxml_node_t *parent, mxml_type_t type);
/*
* 'mxmlAdd()' - Add a node to a tree.
*
* Adds the specified node to the parent. If the child argument is not
* NULL, puts the new node before or after the specified child depending
* on the value of the where argument. If the child argument is NULL,
* puts the new node at the beginning of the child list (MXML_ADD_BEFORE)
* or at the end of the child list (MXML_ADD_AFTER). The constant
* MXML_ADD_TO_PARENT can be used to specify a NULL child pointer.
*/
void
mxmlAdd(mxml_node_t *parent, /* I - Parent node */
int where, /* I - Where to add */
mxml_node_t *child, /* I - Child node for where */
int where, /* I - Where to add, MXML_ADD_BEFORE or MXML_ADD_AFTER */
mxml_node_t *child, /* I - Child node for where or MXML_ADD_TO_PARENT */
mxml_node_t *node) /* I - Node to add */
{
/* fprintf(stderr, "mxmlAdd(parent=%p, where=%d, child=%p, node=%p)\n", parent,
......@@ -151,10 +158,13 @@ mxmlAdd(mxml_node_t *parent, /* I - Parent node */
/*
* 'mxmlDelete()' - Delete a node and all of its children.
*
* If the specified node has a parent, this function first removes the
* node from its parent using the mxmlRemove() function.
*/
void
mxmlDelete(mxml_node_t *node) /* I - Node */
mxmlDelete(mxml_node_t *node) /* I - Node to delete */
{
int i; /* Looping var */
......@@ -230,10 +240,14 @@ mxmlDelete(mxml_node_t *node) /* I - Node */
/*
* 'mxmlNewElement()' - Create a new element node.
*
* The new element node is added to the end of the specified parent's child
* list. The constant MXML_NO_PARENT can be used to specify that the new
* element node has no parent.
*/
mxml_node_t * /* O - New node */
mxmlNewElement(mxml_node_t *parent, /* I - Parent node */
mxmlNewElement(mxml_node_t *parent, /* I - Parent node or MXML_NO_PARENT */
const char *name) /* I - Name of element */
{
mxml_node_t *node; /* New node */
......@@ -259,10 +273,14 @@ mxmlNewElement(mxml_node_t *parent, /* I - Parent node */
/*
* 'mxmlNewInteger()' - Create a new integer node.
*
* The new integer node is added to the end of the specified parent's child
* list. The constant MXML_NO_PARENT can be used to specify that the new
* integer node has no parent.
*/
mxml_node_t * /* O - New node */
mxmlNewInteger(mxml_node_t *parent, /* I - Parent node */
mxmlNewInteger(mxml_node_t *parent, /* I - Parent node or MXML_NO_PARENT */
int integer) /* I - Integer value */
{
mxml_node_t *node; /* New node */
......@@ -288,10 +306,15 @@ mxmlNewInteger(mxml_node_t *parent, /* I - Parent node */
/*
* 'mxmlNewOpaque()' - Create a new opaque string.
*
* The new opaque node is added to the end of the specified parent's child
* list. The constant MXML_NO_PARENT can be used to specify that the new
* opaque node has no parent. The opaque string must be nul-terminated and
* is copied into the new node.
*/
mxml_node_t * /* O - New node */
mxmlNewOpaque(mxml_node_t *parent, /* I - Parent node */
mxmlNewOpaque(mxml_node_t *parent, /* I - Parent node or MXML_NO_PARENT */
const char *opaque) /* I - Opaque string */
{
mxml_node_t *node; /* New node */
......@@ -317,10 +340,14 @@ mxmlNewOpaque(mxml_node_t *parent, /* I - Parent node */
/*
* 'mxmlNewReal()' - Create a new real number node.
*
* The new real number node is added to the end of the specified parent's
* child list. The constant MXML_NO_PARENT can be used to specify that
* the new real number node has no parent.
*/
mxml_node_t * /* O - New node */
mxmlNewReal(mxml_node_t *parent, /* I - Parent node */
mxmlNewReal(mxml_node_t *parent, /* I - Parent node or MXML_NO_PARENT */
double real) /* I - Real number value */
{
mxml_node_t *node; /* New node */
......@@ -346,11 +373,17 @@ mxmlNewReal(mxml_node_t *parent, /* I - Parent node */
/*
* 'mxmlNewText()' - Create a new text fragment node.
*
* The new text node is added to the end of the specified parent's child
* list. The constant MXML_NO_PARENT can be used to specify that the new
* text node has no parent. The whitespace parameter is used to specify
* whether leading whitespace is present before the node. The text
* string must be nul-terminated and is copied into the new node.
*/
mxml_node_t * /* O - New node */
mxmlNewText(mxml_node_t *parent, /* I - Parent node */
int whitespace, /* I - Leading whitespace? */
mxmlNewText(mxml_node_t *parent, /* I - Parent node or MXML_NO_PARENT */
int whitespace, /* I - 1 = leading whitespace, 0 = no whitespace */
const char *string) /* I - String */
{
mxml_node_t *node; /* New node */
......@@ -379,6 +412,9 @@ mxmlNewText(mxml_node_t *parent, /* I - Parent node */
/*
* 'mxmlRemove()' - Remove a node from its parent.
*
* Does not free memory used by the node - use mxmlDelete() for that.
* This function does nothing if the node has no parent.
*/
void
......@@ -453,5 +489,5 @@ mxml_new(mxml_node_t *parent, /* I - Parent node */
/*
* End of "$Id: mxml-node.c,v 1.4 2003/06/05 03:06:20 mike Exp $".
* End of "$Id: mxml-node.c,v 1.5 2003/06/14 23:56:47 mike Exp $".
*/
/*
* "$Id: mxml-search.c,v 1.5 2003/06/06 03:09:31 mike Exp $"
* "$Id: mxml-search.c,v 1.6 2003/06/14 23:56:47 mike Exp $"
*
* Search/navigation functions for mini-XML, a small XML-like file
* parsing library.
......@@ -32,6 +32,15 @@
/*
* 'mxmlFindElement()' - Find the named element.
*
* The search is constrained by the name, attribute name, and value; any
* NULL names or values are treated as wildcards, so different kinds of
* searches can be implemented by looking for all elements of a given name
* or all elements with a specific attribute. The descend argument determines
* whether the search descends into child nodes; normally you will use
* MXML_DESCEND_FIRST for the initial search and MXML_NO_DESCEND to find
* additional direct descendents of the node. The top node argument
* constrains the search to a particular node's children.
*/
mxml_node_t * /* O - Element node or NULL */
......@@ -40,7 +49,7 @@ mxmlFindElement(mxml_node_t *node, /* I - Current node */
const char *name, /* I - Element name or NULL for any */
const char *attr, /* I - Attribute name, or NULL for none */
const char *value, /* I - Attribute value, or NULL for any */
int descend) /* I - Descend into tree? */
int descend) /* I - Descend into tree - MXML_DESCEND, MXML_NO_DESCEND, or MXML_DESCEND_FIRST */
{
const char *temp; /* Current attribute value */
......@@ -110,12 +119,16 @@ mxmlFindElement(mxml_node_t *node, /* I - Current node */
/*
* 'mxmlWalkNext()' - Walk to the next logical node in the tree.
*
* The descend argument controls whether the first child is considered
* to be the next node. The top node argument constrains the walk to
* the node's children.
*/
mxml_node_t * /* O - Next node or NULL */
mxmlWalkNext(mxml_node_t *node, /* I - Current node */
mxml_node_t *top, /* I - Top node */
int descend) /* I - Descend into tree? */
int descend) /* I - Descend into tree - MXML_DESCEND, MXML_NO_DESCEND, or MXML_DESCEND_FIRST */
{
if (!node)
return (NULL);
......@@ -142,12 +155,16 @@ mxmlWalkNext(mxml_node_t *node, /* I - Current node */
/*
* 'mxmlWalkPrev()' - Walk to the previous logical node in the tree.
*
* The descend argument controls whether the previous node's last child
* is considered to be the previous node. The top node argument constrains
* the walk to the node's children.
*/
mxml_node_t * /* O - Previous node or NULL */
mxmlWalkPrev(mxml_node_t *node, /* I - Current node */
mxml_node_t *top, /* I - Top node */
int descend) /* I - Descend into tree? */
int descend) /* I - Descend into tree - MXML_DESCEND, MXML_NO_DESCEND, or MXML_DESCEND_FIRST */
{
if (!node)
return (NULL);
......@@ -177,5 +194,5 @@ mxmlWalkPrev(mxml_node_t *node, /* I - Current node */
/*
* End of "$Id: mxml-search.c,v 1.5 2003/06/06 03:09:31 mike Exp $".
* End of "$Id: mxml-search.c,v 1.6 2003/06/14 23:56:47 mike Exp $".
*/
/*
* "$Id: mxml.h,v 1.8 2003/06/07 21:27:05 mike Exp $"
* "$Id: mxml.h,v 1.9 2003/06/14 23:56:47 mike Exp $"
*
* Header file for mini-XML, a small XML-like file parsing library.
*
......@@ -62,7 +62,7 @@
* Data types...
*/
typedef enum mxml_type_e /**** Node Type ****/
typedef enum mxml_type_e /**** The XML node type. ****/
{
MXML_ELEMENT, /* XML element with attributes */
MXML_INTEGER, /* Integer value */
......@@ -71,26 +71,26 @@ typedef enum mxml_type_e /**** Node Type ****/
MXML_TEXT /* Text fragment */
} mxml_type_t;
typedef struct mxml_attr_s /**** Attribute Value ****/
typedef struct mxml_attr_s /**** An XML element attribute value. ****/
{
char *name; /* Attribute name */
char *value; /* Attribute value */
} mxml_attr_t;
typedef struct mxml_value_s /**** Element Value ****/
typedef struct mxml_value_s /**** An XML element value. ****/
{
char *name; /* Name of element */
int num_attrs; /* Number of attributes */
mxml_attr_t *attrs; /* Attributes */
} mxml_element_t;
typedef struct mxml_text_s /**** Text Value ****/
typedef struct mxml_text_s /**** An XML text value. ****/
{
int whitespace; /* Leading whitespace? */
char *string; /* Fragment string */
} mxml_text_t;
typedef union mxml_value_u /**** Node Value ****/
typedef union mxml_value_u /**** An XML node value. ****/
{
mxml_element_t element; /* Element */
int integer; /* Integer number */
......@@ -99,9 +99,9 @@ typedef union mxml_value_u /**** Node Value ****/
mxml_text_t text; /* Text fragment */
} mxml_value_t;
typedef struct mxml_node_s mxml_node_t;
typedef struct mxml_node_s mxml_node_t; /**** An XML node. ****/
struct mxml_node_s /**** Node ****/
struct mxml_node_s /**** An XML node. ****/
{
mxml_type_t type; /* Node type */
mxml_node_t *next; /* Next node under same parent */
......@@ -162,5 +162,5 @@ extern mxml_node_t *mxmlWalkPrev(mxml_node_t *node, mxml_node_t *top,
/*
* End of "$Id: mxml.h,v 1.8 2003/06/07 21:27:05 mike Exp $".
* End of "$Id: mxml.h,v 1.9 2003/06/14 23:56:47 mike Exp $".
*/
This diff is collapsed.
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment