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.

1 files changed, 52 insertions, 3 deletions

diff --git a/genChRanges.py b/genChRanges.py
index 9f940f30..4962a817 100755
--- a/genChRanges.py
+++ b/genChRanges.py
@@ -241,8 +241,8 @@ struct _xmlChSRange {
 typedef struct _xmlChLRange xmlChLRange;
 typedef xmlChLRange *xmlChLRangePtr;
 struct _xmlChLRange {
-    unsigned		low;
-    unsigned		high;
+    unsigned int	low;
+    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);
 #