enhanced to include enough comments to make the api doc generation happy.

* genChRanges.py, chvalid.c, include/libxml/chvalid.h,
  doc/apibuild.py: enhanced to include enough comments to
  make the api doc generation happy.

ChangeLog

@@ -1,3 +1,9 @@
+Sat Oct 18 20:34:18 HKT 2003 William Brack <wbrack@mmm.com.hk>
+
+	* genChRanges.py, chvalid.c, include/libxml/chvalid.h,
+	  doc/apibuild.py: enhanced to include enough comments to
+	  make the api doc generation happy.
+
 Sat Oct 18 07:28:25 EDT 2003 Daniel Veillard <daniel@veillard.com>
 
 	* nanohttp.c xmlIO.c include/libxml/nanohttp.h: starting work

chvalid.c

@@ -5,7 +5,7 @@
  * This file is automatically generated from the cvs source
  * definition files using the genChRanges.py Python script
  *
- * Generation date: Sat Oct 18 09:01:24 2003
+ * Generation date: Sat Oct 18 20:32:35 2003
  * Sources: chvalid.def
  * William Brack <wbrack@mmm.com.hk>
  */
@@ -149,6 +149,16 @@ xmlChRangeGroup xmlIsIdeographicGroup =
 	{3, 0, xmlIsIdeographic_srng, (xmlChLRangePtr)0};
 
 
+/**
+ * xmlCharInRange:
+ * @val: character to be validated
+ * @rptr: pointer to range to be used to validate
+ *
+ * Does a binary search of the range table to determine if char
+ * is valid
+ *
+ * Returns: true if character valid, false otherwise
+ */
 int
 xmlCharInRange (unsigned int val, xmlChRangeGroupPtr rptr) {
     int low, high, mid;
@@ -195,41 +205,121 @@ xmlCharInRange (unsigned int val, xmlChRangeGroupPtr rptr) {
     return 0;
 }
 
+
+/**
+ * xmlIsBaseChar:
+ * @ch:  character to validate
+ *
+ * This function is DEPRECATED.  Use xmlIsBaseChar_ch
+ * or xmlIsBaseCharQ instead
+ *
+ * Returns true if argument valid, false otherwise
+ */
 int
 xmlIsBaseChar(unsigned int ch) {
     return(xmlIsBaseCharQ(ch));
 }
 
+
+/**
+ * xmlIsBlank:
+ * @ch:  character to validate
+ *
+ * This function is DEPRECATED.  Use xmlIsBlank_ch
+ * or xmlIsBlankQ instead
+ *
+ * Returns true if argument valid, false otherwise
+ */
 int
 xmlIsBlank(unsigned int ch) {
     return(xmlIsBlankQ(ch));
 }
 
+
+/**
+ * xmlIsChar:
+ * @ch:  character to validate
+ *
+ * This function is DEPRECATED.  Use xmlIsChar_ch
+ * or xmlIsCharQ instead
+ *
+ * Returns true if argument valid, false otherwise
+ */
 int
 xmlIsChar(unsigned int ch) {
     return(xmlIsCharQ(ch));
 }
 
+
+/**
+ * xmlIsCombining:
+ * @ch:  character to validate
+ *
+ * This function is DEPRECATED.  Use xmlIsCombining_ch
+ * or xmlIsCombiningQ instead
+ *
+ * Returns true if argument valid, false otherwise
+ */
 int
 xmlIsCombining(unsigned int ch) {
     return(xmlIsCombiningQ(ch));
 }
 
+
+/**
+ * xmlIsDigit:
+ * @ch:  character to validate
+ *
+ * This function is DEPRECATED.  Use xmlIsDigit_ch
+ * or xmlIsDigitQ instead
+ *
+ * Returns true if argument valid, false otherwise
+ */
 int
 xmlIsDigit(unsigned int ch) {
     return(xmlIsDigitQ(ch));
 }
 
+
+/**
+ * xmlIsExtender:
+ * @ch:  character to validate
+ *
+ * This function is DEPRECATED.  Use xmlIsExtender_ch
+ * or xmlIsExtenderQ instead
+ *
+ * Returns true if argument valid, false otherwise
+ */
 int
 xmlIsExtender(unsigned int ch) {
     return(xmlIsExtenderQ(ch));
 }
 
+
+/**
+ * xmlIsIdeographic:
+ * @ch:  character to validate
+ *
+ * This function is DEPRECATED.  Use xmlIsIdeographic_ch
+ * or xmlIsIdeographicQ instead
+ *
+ * Returns true if argument valid, false otherwise
+ */
 int
 xmlIsIdeographic(unsigned int ch) {
     return(xmlIsIdeographicQ(ch));
 }
 
+
+/**
+ * xmlIsPubidChar:
+ * @ch:  character to validate
+ *
+ * This function is DEPRECATED.  Use xmlIsPubidChar_ch
+ * or xmlIsPubidCharQ instead
+ *
+ * Returns true if argument valid, false otherwise
+ */
 int
 xmlIsPubidChar(unsigned int ch) {
     return(xmlIsPubidCharQ(ch));

doc/apibuild.py

@@ -25,7 +25,6 @@ ignored_files = {
   "testOOM.c": "out of memory tester",
   "testOOMlib.h": "out of memory tester",
   "testOOMlib.c": "out of memory tester",
-  "chvalid.h":  "internal only + parsing problems",
   "pattern.c": "not integrated yet",
   "pattern.h": "not integrated yet",
 }

genChRanges.py

@@ -241,8 +241,8 @@ struct _xmlChSRange {
 typedef struct _xmlChLRange xmlChLRange;
 typedef xmlChLRange *xmlChLRangePtr;
 struct _xmlChLRange {
-    unsigned		low;
+    unsigned int	low;
-    unsigned		high;
+    unsigned int	high;
 };
 
 typedef struct _xmlChRangeGroup xmlChRangeGroup;
@@ -254,7 +254,9 @@ struct _xmlChRangeGroup {
     xmlChLRangePtr	longRange;
 };
 
-/* Range checking routine */
+/**
+ * Range checking routine
+ */
 XMLPUBFUN int XMLCALL
 		xmlCharInRange(unsigned int val, const xmlChRangeGroupPtr group);
 
@@ -307,6 +309,14 @@ for f in fkeys:
 	numRanges = len(rangeTable)
 	if numRanges >= minTableSize:	# table is worthwhile
 	    header.write("XMLPUBVAR unsigned char %s_tab[256];\n" % f)
+	    header.write("""
+/**
+ * %s_ch:
+ * @c: char to validate
+ *
+ * Automatically generated by genChRanges.py
+ */
+""" % f)
 	    header.write("#define %s_ch(c)\t(%s_tab[(c)])\n" % (f, f))
 
 	    # write the constant data to the code file
@@ -328,6 +338,16 @@ for f in fkeys:
 	    except:
 		pass
 	    firstFlag = 1
+	    
+	    header.write("""
+/**
+ * %s_ch:
+ *
+ * @c: char to validate
+ *
+ * Automatically generated by genChRanges.py
+ */
+""" % f)
 	    # okay, I'm tired of the messy lineup - let's automate it!
 	    pline = "#define %s_ch(c)" % f
 	    # 'ntab' is number of tabs needed to position to col. 33 from name end
@@ -351,6 +371,14 @@ for f in fkeys:
 	    pline += ")\n"
 	    header.write(pline)
 
+    header.write("""
+/**
+ * %sQ:
+ * @c: char to validate
+ *
+ * Automatically generated by genChRanges.py
+ */
+""" % f)
     pline = "#define %sQ(c)" % f
     ntab = 4 - (len(pline)) / 8
     if ntab < 0:
@@ -441,6 +469,16 @@ for f in fkeys:
 
 output.write(
 """
+/**
+ * xmlCharInRange:
+ * @val: character to be validated
+ * @rptr: pointer to range to be used to validate
+ *
+ * Does a binary search of the range table to determine if char
+ * is valid
+ *
+ * Returns: true if character valid, false otherwise
+ */
 int
 xmlCharInRange (unsigned int val, xmlChRangeGroupPtr rptr) {
     int low, high, mid;
@@ -493,6 +531,17 @@ xmlCharInRange (unsigned int val, xmlChRangeGroupPtr rptr) {
 # finally, generate the ABI compatibility functions
 #
 for f in fkeys:
+    output.write("""
+/**
+ * %s:
+ * @ch:  character to validate
+ *
+ * This function is DEPRECATED.  Use %s_ch
+ * or %sQ instead
+ *
+ * Returns true if argument valid, false otherwise
+ */
+""" % (f, f, f))
     output.write("int\n%s(unsigned int ch) {\n    return(%sQ(ch));\n}\n\n" % (f,f))
     header.write("XMLPUBFUN int XMLCALL\n\t\t%s(unsigned int ch);\n" % f);
 #

include/libxml/chvalid.h

@@ -5,7 +5,7 @@
  * This file is automatically generated from the cvs source
  * definition files using the genChRanges.py Python script
  *
- * Generation date: Sat Oct 18 09:01:24 2003
+ * Generation date: Sat Oct 18 20:32:35 2003
  * Sources: chvalid.def
  * William Brack <wbrack@mmm.com.hk>
  */
@@ -33,8 +33,8 @@ struct _xmlChSRange {
 typedef struct _xmlChLRange xmlChLRange;
 typedef xmlChLRange *xmlChLRangePtr;
 struct _xmlChLRange {
-    unsigned		low;
+    unsigned int	low;
-    unsigned		high;
+    unsigned int	high;
 };
 
 typedef struct _xmlChRangeGroup xmlChRangeGroup;
@@ -46,29 +46,76 @@ struct _xmlChRangeGroup {
     xmlChLRangePtr	longRange;
 };
 
-/* Range checking routine */
+/**
+ * Range checking routine
+ */
 XMLPUBFUN int XMLCALL
 		xmlCharInRange(unsigned int val, const xmlChRangeGroupPtr group);
 
+
+/**
+ * xmlIsBaseChar_ch:
+ *
+ * @c: char to validate
+ *
+ * Automatically generated by genChRanges.py
+ */
 #define xmlIsBaseChar_ch(c)	(((0x41 <= (c)) && ((c) <= 0x5a)) || \
 				 ((0x61 <= (c)) && ((c) <= 0x7a)) || \
 				 ((0xc0 <= (c)) && ((c) <= 0xd6)) || \
 				 ((0xd8 <= (c)) && ((c) <= 0xf6)) || \
 				 ((0xf8 <= (c)) && ((c) <= 0xff)))
+
+/**
+ * xmlIsBaseCharQ:
+ * @c: char to validate
+ *
+ * Automatically generated by genChRanges.py
+ */
 #define xmlIsBaseCharQ(c)	(((c) < 0x100) ? \
 				 xmlIsBaseChar_ch((c)) : \
 				 xmlCharInRange((c), &xmlIsBaseCharGroup))
 
 XMLPUBVAR xmlChRangeGroup xmlIsBaseCharGroup;
+
+/**
+ * xmlIsBlank_ch:
+ *
+ * @c: char to validate
+ *
+ * Automatically generated by genChRanges.py
+ */
 #define xmlIsBlank_ch(c)	(((c) == 0x20) || \
 				 ((0x9 <= (c)) && ((c) <= 0xa)) || \
 				 ((c) == 0xd))
+
+/**
+ * xmlIsBlankQ:
+ * @c: char to validate
+ *
+ * Automatically generated by genChRanges.py
+ */
 #define xmlIsBlankQ(c)		(((c) < 0x100) ? \
 				 xmlIsBlank_ch((c)) : 0)
 
+
+/**
+ * xmlIsChar_ch:
+ *
+ * @c: char to validate
+ *
+ * Automatically generated by genChRanges.py
+ */
 #define xmlIsChar_ch(c)		(((0x9 <= (c)) && ((c) <= 0xa)) || \
 				 ((c) == 0xd) || \
 				 ((0x20 <= (c)) && ((c) <= 0xff)))
+
+/**
+ * xmlIsCharQ:
+ * @c: char to validate
+ *
+ * Automatically generated by genChRanges.py
+ */
 #define xmlIsCharQ(c)		(((c) < 0x100) ? \
 				 xmlIsChar_ch((c)) :\
 				(((0x100 <= (c)) && ((c) <= 0xd7ff)) || \
@@ -76,23 +123,67 @@ XMLPUBVAR xmlChRangeGroup xmlIsBaseCharGroup;
 				 ((0x10000 <= (c)) && ((c) <= 0x10ffff))))
 
 XMLPUBVAR xmlChRangeGroup xmlIsCharGroup;
+
+/**
+ * xmlIsCombiningQ:
+ * @c: char to validate
+ *
+ * Automatically generated by genChRanges.py
+ */
 #define xmlIsCombiningQ(c)	(((c) < 0x100) ? \
 				 0 : \
 				 xmlCharInRange((c), &xmlIsCombiningGroup))
 
 XMLPUBVAR xmlChRangeGroup xmlIsCombiningGroup;
+
+/**
+ * xmlIsDigit_ch:
+ *
+ * @c: char to validate
+ *
+ * Automatically generated by genChRanges.py
+ */
 #define xmlIsDigit_ch(c)	(((0x30 <= (c)) && ((c) <= 0x39)))
+
+/**
+ * xmlIsDigitQ:
+ * @c: char to validate
+ *
+ * Automatically generated by genChRanges.py
+ */
 #define xmlIsDigitQ(c)		(((c) < 0x100) ? \
 				 xmlIsDigit_ch((c)) : \
 				 xmlCharInRange((c), &xmlIsDigitGroup))
 
 XMLPUBVAR xmlChRangeGroup xmlIsDigitGroup;
+
+/**
+ * xmlIsExtender_ch:
+ *
+ * @c: char to validate
+ *
+ * Automatically generated by genChRanges.py
+ */
 #define xmlIsExtender_ch(c)	(((c) == 0xb7))
+
+/**
+ * xmlIsExtenderQ:
+ * @c: char to validate
+ *
+ * Automatically generated by genChRanges.py
+ */
 #define xmlIsExtenderQ(c)	(((c) < 0x100) ? \
 				 xmlIsExtender_ch((c)) : \
 				 xmlCharInRange((c), &xmlIsExtenderGroup))
 
 XMLPUBVAR xmlChRangeGroup xmlIsExtenderGroup;
+
+/**
+ * xmlIsIdeographicQ:
+ * @c: char to validate
+ *
+ * Automatically generated by genChRanges.py
+ */
 #define xmlIsIdeographicQ(c)	(((c) < 0x100) ? \
 				 0 :\
 				(((0x4e00 <= (c)) && ((c) <= 0x9fa5)) || \
@@ -101,7 +192,21 @@ XMLPUBVAR xmlChRangeGroup xmlIsExtenderGroup;
 
 XMLPUBVAR xmlChRangeGroup xmlIsIdeographicGroup;
 XMLPUBVAR unsigned char xmlIsPubidChar_tab[256];
+
+/**
+ * xmlIsPubidChar_ch:
+ * @c: char to validate
+ *
+ * Automatically generated by genChRanges.py
+ */
 #define xmlIsPubidChar_ch(c)	(xmlIsPubidChar_tab[(c)])
+
+/**
+ * xmlIsPubidCharQ:
+ * @c: char to validate
+ *
+ * Automatically generated by genChRanges.py
+ */
 #define xmlIsPubidCharQ(c)	(((c) < 0x100) ? \
 				 xmlIsPubidChar_ch((c)) : 0)