Use doxygen to create API documentation.

Add a bunch of extra commentary to stop doxygen warning.

svn path=/trunk/hubbub/; revision=5994

7 files changed, 53 insertions, 31 deletions

diff --git a/src/tokeniser/entities.c b/src/tokeniser/entities.c
index 23756a6..8bea1aa 100644
--- a/src/tokeniser/entities.c
+++ b/src/tokeniser/entities.c
@@ -11,9 +11,12 @@
 
 typedef struct hubbub_entity hubbub_entity;
 
+/**
+ * Entity mapping table
+ */
 static const struct hubbub_entity {
-	const char *name;
-	uint32_t ucs4;
+	const char *name;		/**< Entity name */
+	uint32_t ucs4;			/**< UCS-4 codepoint */
 } entities[] = {
 	{ "Aacute;", 0x000C1 },
 	{ "Aacute", 0x000C1 },
diff --git a/src/tokeniser/tokeniser.c b/src/tokeniser/tokeniser.c
index 6ffa8b7..fbc9534 100644
--- a/src/tokeniser/tokeniser.c
+++ b/src/tokeniser/tokeniser.c
@@ -107,21 +107,22 @@ typedef struct hubbub_tokeniser_context {
 
 	uint8_t last_start_tag_name[10];	/**< Name of the last start tag
 						 * emitted */
-	size_t last_start_tag_len;
+	size_t last_start_tag_len;		/**< Length of last start tag */
 
 	struct {
 		uint32_t count;
 		bool match;
-	} close_tag_match;
+	} close_tag_match;			/**< State for matching close 
+						 * tags */
 
 	struct {
 		uint32_t count;			/**< Index into "DOCTYPE" */
-	} match_doctype;
+	} match_doctype;			/**< State for matching doctype */
 
 	struct {
 		uint32_t count;			/**< Index into "[CDATA[" */
 		uint32_t end;			/**< Index into "]]>" */
-	} match_cdata;
+	} match_cdata;				/**< State for matching cdata */
 
 	struct {
 		size_t offset;			/**< Offset in buffer */
@@ -145,15 +146,15 @@ typedef struct hubbub_tokeniser_context {
 						 * numeric entity value */
 		hubbub_tokeniser_state return_state;	/**< State we were
 							 * called from */
-	} match_entity;
+	} match_entity;				/**< Entity matching state */
 
 	struct {
 		uint32_t line;			/**< Current line of input */
 		uint32_t col;			/**< Current character in
 						 * line */
-	} position;
+	} position;				/**< Position in source data */
 
-	uint32_t allowed_char;
+	uint32_t allowed_char;			/**< Used for quote matching */
 } hubbub_tokeniser_context;
 
 /**
@@ -164,18 +165,18 @@ struct hubbub_tokeniser {
 	hubbub_content_model content_model;	/**< Current content
 						 * model flag */
 	bool escape_flag;		/**< Escape flag **/
-	bool process_cdata_section;
+	bool process_cdata_section;	/**< Whether to process CDATA sections*/
 
 	parserutils_inputstream *input;	/**< Input stream */
 	parserutils_buffer *buffer;	/**< Input buffer */
 
 	hubbub_tokeniser_context context;	/**< Tokeniser context */
 
-	hubbub_token_handler token_handler;
-	void *token_pw;
+	hubbub_token_handler token_handler;	/**< Token handling callback */
+	void *token_pw;				/**< Token handler data */
 
-	hubbub_error_handler error_handler;
-	void *error_pw;
+	hubbub_error_handler error_handler;	/**< Error handling callback */
+	void *error_pw;				/**< Error handler data */
 
 	hubbub_alloc alloc;		/**< Memory (de)allocation function */
 	void *alloc_pw;			/**< Client private data */
diff --git a/src/tokeniser/tokeniser.h b/src/tokeniser/tokeniser.h
index a5bc8de..0ccb7d1 100644
--- a/src/tokeniser/tokeniser.h
+++ b/src/tokeniser/tokeniser.h
@@ -36,18 +36,18 @@ typedef union hubbub_tokeniser_optparams {
 	struct {
 		hubbub_token_handler handler;
 		void *pw;
-	} token_handler;
+	} token_handler;		/**< Token handling callback */
 
 	struct {
 		hubbub_error_handler handler;
 		void *pw;
-	} error_handler;
+	} error_handler;		/**< Error handling callback */
 
 	struct {
 		hubbub_content_model model;
-	} content_model;
+	} content_model;		/**< Current content model */
 
-	bool process_cdata;
+	bool process_cdata;		/**< Whether to process CDATA sections*/
 } hubbub_tokeniser_optparams;
 
 /* Create a hubbub tokeniser */
diff --git a/src/treebuilder/in_body.c b/src/treebuilder/in_body.c
index f9fbfe7..8de663b 100644
--- a/src/treebuilder/in_body.c
+++ b/src/treebuilder/in_body.c
@@ -15,9 +15,12 @@
 
 #undef DEBUG_IN_BODY
 
+/**
+ * Bookmark for formatting list. Used in adoption agency
+ */
 typedef struct bookmark {
-	formatting_list_entry *prev;
-	formatting_list_entry *next;
+	formatting_list_entry *prev;	/**< Previous entry */
+	formatting_list_entry *next;	/**< Next entry */
 } bookmark;
 
 static void process_character(hubbub_treebuilder *treebuilder,
diff --git a/src/treebuilder/in_foreign_content.c b/src/treebuilder/in_foreign_content.c
index 8cb17d8..9b09752 100644
--- a/src/treebuilder/in_foreign_content.c
+++ b/src/treebuilder/in_foreign_content.c
@@ -19,11 +19,14 @@
 
 #define S(s)		s, SLEN(s)
 
+/**
+ * Mapping table for case changes
+ */
 typedef struct
 {
-	const char *attr;
-	size_t len;
-	const char *proper;
+	const char *attr;	/**< Lower case attribute name */
+	size_t len;		/**< Length of name in bytes */
+	const char *proper;	/**< Correctly cased version */
 } case_changes;
 
 static const case_changes svg_attributes[] = {
diff --git a/src/treebuilder/internal.h b/src/treebuilder/internal.h
index 6e5d80f..0649f25 100644
--- a/src/treebuilder/internal.h
+++ b/src/treebuilder/internal.h
@@ -36,6 +36,9 @@ typedef enum
 	UNKNOWN,
 } element_type;
 
+/**
+ * Item on the element stack
+ */
 typedef struct element_context
 {
 	hubbub_ns ns;			/**< Element namespace */
@@ -51,6 +54,9 @@ typedef struct element_context
 	void *node;			/**< Node pointer */
 } element_context;
 
+/**
+ * Entry in a formatting list
+ */
 typedef struct formatting_list_entry
 {
 	element_context details;	/**< Entry details */
@@ -61,6 +67,9 @@ typedef struct formatting_list_entry
 	struct formatting_list_entry *next;	/**< Next in list */
 } formatting_list_entry;
 
+/**
+ * Context for a tree builder
+ */
 typedef struct hubbub_treebuilder_context
 {
 	insertion_mode mode;		/**< The current insertion mode */
@@ -100,16 +109,19 @@ typedef struct hubbub_treebuilder_context
 					* be foster parented */
 } hubbub_treebuilder_context;
 
+/**
+ * Treebuilder object
+ */
 struct hubbub_treebuilder
 {
 	hubbub_tokeniser *tokeniser;	/**< Underlying tokeniser */
 
-	hubbub_treebuilder_context context;
+	hubbub_treebuilder_context context;	/**< Our context */
 
-	hubbub_tree_handler *tree_handler;
+	hubbub_tree_handler *tree_handler;	/**< Callback table */
 
-	hubbub_error_handler error_handler;
-	void *error_pw;
+	hubbub_error_handler error_handler;	/**< Error handler */
+	void *error_pw;				/**< Error handler data */
 
 	hubbub_alloc alloc;		/**< Memory (de)allocation function */
 	void *alloc_pw;			/**< Client private data */
diff --git a/src/treebuilder/treebuilder.h b/src/treebuilder/treebuilder.h
index 0f883ec..ba5db1a 100644
--- a/src/treebuilder/treebuilder.h
+++ b/src/treebuilder/treebuilder.h
@@ -37,13 +37,13 @@ typedef union hubbub_treebuilder_optparams {
 	struct {
 		hubbub_error_handler handler;
 		void *pw;
-	} error_handler;
+	} error_handler;			/**< Error handling callback */
 
-	hubbub_tree_handler *tree_handler;
+	hubbub_tree_handler *tree_handler;	/**< Tree handling callbacks */
 
-	void *document_node;
+	void *document_node;			/**< The document node */
 
-	bool enable_scripting;
+	bool enable_scripting;			/**< Enable scripting */
 } hubbub_treebuilder_optparams;
 
 /* Create a hubbub treebuilder */