Minor changes to comments, etc. for improving documentation generation

* encoding.c, threads.c, include/libxml/HTMLparser.h,
  doc/libxml2-api.xml: Minor changes to comments, etc. for
  improving documentation generation
* doc/Makefile.am: further adjustment to auto-generation of
  win32/libxml2.def.src

ChangeLog

@@ -1,3 +1,11 @@
+Fri Aug 15 14:58:37 HKT 2003 William Brack <wbrack@mmm.com.hk>
+
+	* encoding.c, threads.c, include/libxml/HTMLparser.h,
+	  doc/libxml2-api.xml: Minor changes to comments, etc. for
+	  improving documentation generation
+	* doc/Makefile.am: further adjustment to auto-generation of
+	  win32/libxml2.def.src
+	  
 Fri Aug 15 02:24:20 CEST 2003 Daniel Veillard <daniel@veillard.com>
 
 	* News configure.in: preparing libxml2-2.5.10 release

doc/Makefile.am

@@ -69,10 +69,10 @@ xml: templates
 	-gtkdoc-mkdb --module=libxml --source-dir=$(DOC_SOURCE_DIR) --output-format=xml --main-sgml-file=$(DOC_MAIN_XML_FILE)
 
 
-libxml2-api.xml: apibuild.py ../include/libxml/*.h
+libxml2-api.xml: apibuild.py ../include/libxml/*.h ../*.c
 	-(./apibuild.py)
 
-$(WIN32_DIR)/libxml2.def.src:
+$(WIN32_DIR)/libxml2.def.src: libxml2-api.xml
 	-@(if [ -x $(bindir)/xsltproc ] ; then \
 	  $(bindir)/xsltproc -o $(WIN32_DIR)/libxml2.def.src \
 	  --nonet $(WIN32_DIR)/defgen.xsl libxml2-api.xml ; fi )

encoding.c

@@ -92,6 +92,8 @@ static int xmlLittleEndian = 1;
  * xmlUTF8Size:
  * @utf: pointer to the UTF8 character
  *
+ * calulates the internal size of a UTF8 character
+ *
  * returns the numbers of bytes in the character, -1 on format error
  */
 int
@@ -117,12 +119,13 @@ xmlUTF8Size(const xmlChar *utf) {
 }
 
 /**
- * xmlUTF8Charcmp
+ * xmlUTF8Charcmp:
  * @utf1: pointer to first UTF8 char
  * @utf2: pointer to second UTF8 char
  *
- * returns result of comparing the two UCS4 values
+ * compares the two UCS4 values
- * as with xmlStrncmp
+ *
+ * returns result of the compare as with xmlStrncmp
  */
 int
 xmlUTF8Charcmp(const xmlChar *utf1, const xmlChar *utf2) {

include/libxml/HTMLparser.h

@@ -149,9 +149,31 @@ htmlStatus htmlAttrAllowed(const htmlElemDesc*, const xmlChar*, int) ;
 int htmlElementAllowedHere(const htmlElemDesc*, const xmlChar*) ;
 htmlStatus htmlElementStatusHere(const htmlElemDesc*, const htmlElemDesc*) ;
 htmlStatus htmlNodeStatus(const htmlNodePtr, int) ;
+/**
+ * htmlDefaultSubelement:
+ * @elt: HTML element
+ *
+ * Returns the default subelement for this element
+ */
 #define htmlDefaultSubelement(elt) elt->defaultsubelt
+/**
+ * htmlElementAllowedHereDesc:
+ * @parent: HTML parent element
+ * @elt: HTML element
+ *
+ * Checks whether an HTML element description may be a
+ * direct child of the specified element.
+ *
+ * Returns 1 if allowed; 0 otherwise.
+ */
 #define htmlElementAllowedHereDesc(parent,elt) \
 	htmlElementAllowedHere((parent), (elt)->name)
+/**
+ * htmlRequiredAttrs:
+ * @elt: HTML element
+ *
+ * Returns the attributes required for the specified element.
+ */
 #define htmlRequiredAttrs(elt) (elt)->attrs_req
 
 

threads.c

@@ -546,10 +546,15 @@ xmlOnceInit(void) {
 }
 
 /**
- * DllMain
+ * DllMain:
+ * @hinstDLL: handle to DLL instance
+ * @fdwReason: Reason code for entry
+ * @lpvReserved: generic pointer (depends upon reason code)
  *
  * Entry point for Windows library. It is being used to free thread-specific
  * storage.
+ *
+ * Returns TRUE always
  */
 #if defined(HAVE_WIN32_THREADS) && !defined(LIBXML_STATIC)
 BOOL WINAPI DllMain(HINSTANCE hinstDLL, DWORD fdwReason, LPVOID lpvReserved)