Don't index anything in DOC_DISABLE sections

Somewhat misleadingly, the DOC_DISABLE directive only disabled warnings.
Now we really stop the documentation generator from indexing.

This results in additional warnings for xmlThrDef* functions. This should
be fixed by documenting or deprecating them.

Author: nwellnhof

doc/apibuild.py

@@ -577,23 +577,25 @@ def __init__(self, filename, idx = None):
         self.last_comment = ""
         self.comment = None
         self.collect_ref = 0
-        self.no_error = 0
+        self.doc_disable = 0
         self.conditionals = []
         self.defines = []
 
     def collect_references(self):
         self.collect_ref = 1
 
-    def stop_error(self):
-        self.no_error = 1
+    def disable(self):
+        self.doc_disable = 1
 
-    def start_error(self):
-        self.no_error = 0
+    def enable(self):
+        self.doc_disable = 0
 
     def lineno(self):
         return self.lexer.getlineno()
 
     def index_add(self, name, module, static, type, info=None, extra = None):
+        if self.doc_disable:
+            return
         if self.is_header == 1:
             self.index.add(name, module, module, static, type, self.lineno(),
                            info, extra, self.conditionals)
@@ -611,12 +613,12 @@ def index_add_ref(self, name, module, static, type, info=None,
                                info, extra, self.conditionals)
 
     def warning(self, msg):
-        if self.no_error:
+        if self.doc_disable:
             return
         print(msg)
 
     def error(self, msg, token=-1):
-        if self.no_error:
+        if self.doc_disable:
             return
 
         print("Parse Error: " + msg)
@@ -669,10 +671,10 @@ def parseComment(self, token):
         token = self.lexer.token()
 
         if self.comment.find("DOC_DISABLE") != -1:
-            self.stop_error()
+            self.disable()
 
         if self.comment.find("DOC_ENABLE") != -1:
-            self.start_error()
+            self.enable()
 
         return token
 
@@ -935,7 +937,7 @@ def parsePreproc(self, token):
                     name = name.split('(') [0]
                 except:
                     pass
-                info = self.parseMacroComment(name, not self.is_header)
+                info = self.parseMacroComment(name, True)
                 self.index_add(name, self.filename, not self.is_header,
                                 "macro", info)
                 return token

doc/libxml2-api.xml

@@ -1387,7 +1387,6 @@
      <author>Daniel Veillard </author>
      <exports symbol='BASE_BUFFER_SIZE' type='macro'/>
      <exports symbol='LIBXML2_NEW_BUFFER' type='macro'/>
-     <exports symbol='XML_DOCB_DOCUMENT_NODE' type='macro'/>
      <exports symbol='XML_GET_CONTENT' type='macro'/>
      <exports symbol='XML_GET_LINE' type='macro'/>
      <exports symbol='XML_LOCAL_NAMESPACE' type='macro'/>
@@ -2763,7 +2762,6 @@
     <file name='xmlexports'>
      <summary>macros for marking symbols as exportable/importable.</summary>
      <description>macros for marking symbols as exportable/importable. </description>
-     <exports symbol='LIBXML_DLL_IMPORT' type='macro'/>
      <exports symbol='XMLCALL' type='macro'/>
      <exports symbol='XMLCDECL' type='macro'/>
      <exports symbol='XMLPUBFUN' type='macro'/>
@@ -3963,8 +3961,6 @@
     <macro name='LIBXML_DEBUG_RUNTIME' file='xmlversion'>
       <info>Whether the runtime debugging is configured in</info>
     </macro>
-    <macro name='LIBXML_DLL_IMPORT' file='xmlexports'>
-    </macro>
     <macro name='LIBXML_DOTTED_VERSION' file='xmlversion'>
       <info>the version string like &quot;1.2.3&quot;</info>
     </macro>
@@ -4158,8 +4154,6 @@
     <macro name='XML_DETECT_IDS' file='parser'>
       <info>Bit in the loadsubset context field to tell to do ID/REFs lookups. Use it to initialize xmlLoadExtDtdDefaultValue.</info>
     </macro>
-    <macro name='XML_DOCB_DOCUMENT_NODE' file='tree'>
-    </macro>
     <macro name='XML_GET_CONTENT' file='tree'>
       <info>Macro to extract the content pointer of a node.</info>
     </macro>
@@ -4466,12 +4460,6 @@
     <macro name='XML_XPATH_NOVAR' file='xpath'>
       <info>forbid variables in expression</info>
     </macro>
-    <macro name='XPATH_LOCATIONSET' file='xpath'>
-    </macro>
-    <macro name='XPATH_POINT' file='xpath'>
-    </macro>
-    <macro name='XPATH_RANGE' file='xpath'>
-    </macro>
     <macro name='XP_ERROR' file='xpathInternals'>
       <info>Macro to raise an XPath error and return.</info>
       <arg name='X' info='the error code'/>

globals.c

@@ -559,10 +559,6 @@ void xmlCleanupGlobals(void)
     __xmlGlobalInitMutexDestroy();
 }
 
-/**
- * DOC_DISABLE : we ignore missing doc for the xmlThrDef functions,
- *               those are really internal work
- */
 void
 xmlThrDefSetGenericErrorFunc(void *ctx, xmlGenericErrorFunc handler) {
     xmlMutexLock(xmlThrDefMutex);

include/libxml/globals.h

@@ -192,7 +192,6 @@ XMLPUBFUN xmlParserInputBufferCreateFilenameFunc XMLCALL
 	xmlThrDefParserInputBufferCreateFilenameDefault(
 				xmlParserInputBufferCreateFilenameFunc func);
 
-/** DOC_DISABLE */
 /*
  * In general the memory allocation entry points are not kept
  * thread specific but this can be overridden by LIBXML_THREAD_ALLOC_ENABLED
@@ -204,6 +203,8 @@ XMLPUBFUN xmlParserInputBufferCreateFilenameFunc XMLCALL
  */
 
 #ifdef LIBXML_THREAD_ALLOC_ENABLED
+/** DOC_DISABLE */
+
 #ifdef LIBXML_THREAD_ENABLED
 XMLPUBFUN  xmlMallocFunc * XMLCALL __xmlMalloc(void);
 #define xmlMalloc \
@@ -244,6 +245,7 @@ XMLPUBFUN  xmlStrdupFunc * XMLCALL __xmlMemStrdup(void);
 XMLPUBVAR xmlStrdupFunc xmlMemStrdup;
 #endif
 
+/** DOC_ENABLE */
 #else /* !LIBXML_THREAD_ALLOC_ENABLED */
 XMLPUBVAR xmlMallocFunc xmlMalloc;
 XMLPUBVAR xmlMallocFunc xmlMallocAtomic;