[Incomplete do not merge] Enhance undocumented feature

src/config.xml

@@ -1349,6 +1349,24 @@ FILE_VERSION_FILTER = "cleartool desc -fmt \%Vn"
  If the \c WARN_IF_UNDOCUMENTED tag is set to \c YES then doxygen will generate warnings
  for undocumented members. If \ref cfg_extract_all "EXTRACT_ALL" is set to \c YES then this flag will
  automatically be disabled.
+]]>
+      </docs>
+    </option>
+    <option type='bool' id='WARN_IF_UNDOCUMENTED_CLASS' defval='1'>
+      <docs>
+<![CDATA[
+ If the \c WARN_IF_UNDOCUMENTED_CLASS tag is set to \c YES then doxygen will generate warnings
+ for undocumented classes and structs. If \ref cfg_extract_all "EXTRACT_ALL" is set to \c YES then this flag will
+ automatically be disabled.
+]]>
+      </docs>
+    </option>
+    <option type='bool' id='WARN_IF_UNDOCUMENTED_NAMESPACE' defval='1'>
+      <docs>
+<![CDATA[
+ If the \c WARN_IF_UNDOCUMENTED_NAMESPACE tag is set to \c YES then doxygen will generate warnings
+ for undocumented namespaces. If \ref cfg_extract_all "EXTRACT_ALL" is set to \c YES then this flag will
+ automatically be disabled.
 ]]>
       </docs>
     </option>

testing/103/103__undocumented__member_8cpp.xml

@@ -0,0 +1,12 @@
+<?xml version='1.0' encoding='UTF-8' standalone='no'?>
+<doxygen xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="compound.xsd" version="1.11.0" xml:lang="en-US">
+  <compounddef id="103__undocumented__members_8cpp" kind="file" language="C++">
+    <compoundname>103_undocumented_members.cpp</compoundname>
+    <innerclass refid="class_test_class" prot="public">TestClass</innerclass>
+    <briefdescription>
+    </briefdescription>
+    <detaileddescription>
+    </detaileddescription>
+    <location file="103_undocumented_members.cpp"/>
+  </compounddef>
+</doxygen>

testing/103_undocumented_member.cpp

@@ -0,0 +1,9 @@
+// objective: Test the WARN_IF_UNDOCUMENTED feature when set to YES
+// check: 103__undocumented__member_8cpp.xml
+// config: WARN_IF_UNDOCUMENTED=YES
+// expected_warning_patterns: "warning: Member undocumentedFunction() in class TestClass is undocumented."
+
+/*   * @brief Test class for undocumented methods */
+class TestClass {
+    void undocumentedFunction(); // This function is undocumented and should trigger a warning.
+};

testing/104/104__undocumented__namespace_8cpp.xml

@@ -0,0 +1,12 @@
+<?xml version='1.0' encoding='UTF-8' standalone='no'?>
+<doxygen xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="compound.xsd" version="1.11.0" xml:lang="en-US">
+  <compounddef id="104__undocumented__namespace_8cpp" kind="file" language="C++">
+    <compoundname>104_undocumented_namespace.cpp</compoundname>
+    <innernamespace refid="namespace_undocumented_namespace">UndocumentedNamespace</innernamespace>
+    <briefdescription>
+    </briefdescription>
+    <detaileddescription>
+    </detaileddescription>
+    <location file="104_undocumented_namespace.cpp"/>
+  </compounddef>
+</doxygen>

testing/104_undocumented_namespace.cpp

@@ -0,0 +1,9 @@
+// objective: Test the WARN_IF_UNDOCUMENTED feature when set to YES
+// check: 104__undocumented__namespace_8cpp.xml
+// config: WARN_IF_UNDOCUMENTED_NAMESPACE=YES
+// expected_warning_patterns: "warning: Namespace undocumentedNamespace is undocumented."
+
+// This namespace is undocumented and should trigger a warning.
+namespace UndocumentedNamespace {
+    void undocumentedFunction();
+}

testing/105_undocumented_class.cpp

@@ -0,0 +1,9 @@
+// objective: Test the WARN_IF_UNDOCUMENTED feature when set to YES
+// check: 103__undocumented__members_8cpp.xml
+// config: WARN_IF_UNDOCUMENTED=YES
+// expected_warning_patterns: "warning: Member undocumentedFunction() in class TestClass is undocumented."
+
+/** @brief Test class for undocumented methods */
+class TestClass {
+    void undocumentedFunction(); // This function is undocumented and should trigger a warning.
+};

testing/runtests.py

@@ -28,6 +28,7 @@ def xpopen(cmd, cmd1="",encoding='utf-8-sig', getStderr=False):
     Python 2 does not have the encoding argument. Python 3 has one. and
     '''
 
+    print('Running cmd: %s' % cmd)
     if sys.version_info[0] == 2:
         return os.popen(cmd).read() # Python 2 without encoding
     else:
@@ -196,6 +197,7 @@ def prepare_test(self):
         if (self.args.noredir):
             redir=''
 
+        print('Running doxygen: os.system("%s %s/Doxyfile %s")' % (self.args.doxygen,self.test_out,redir))
         if os.system('%s %s/Doxyfile %s' % (self.args.doxygen,self.test_out,redir))!=0:
             print('Error: failed to run %s on %s/Doxyfile' % (self.args.doxygen,self.test_out))
             sys.exit(1)
@@ -263,6 +265,22 @@ def update_test(self,testmgr):
         os.remove(self.test_out+'/Doxyfile')
         return True
 
+    # check the warnings log file for any unexpected warnings
+    def check_warnings(self,log_file_path,expected_warning_patterns):
+        with xopen(log_file_path, 'r', encoding='ISO-8859-1') as log_file:
+            log_contents = log_file.readlines()
+
+        unexpected_warnings = []
+        missing_warnings = set(expected_warning_patterns)
+        for line in log_contents:
+            if not any(re.search(pattern, line) for pattern in expected_warning_patterns):
+                unexpected_warnings.append(line)
+            for pattern in expected_warning_patterns:
+                if re.search(pattern, line):
+                    missing_warnings.discard(pattern)
+
+        return unexpected_warnings, missing_warnings
+
     # check the relevant files of a doxygen run with the reference material
     def perform_test(self,testmgr):
         if (sys.platform == 'win32'):
@@ -519,10 +537,19 @@ def perform_test(self,testmgr):
             elif not self.args.keep:
                 shutil.rmtree(latex_output,ignore_errors=True)
 
-        warnings = xopen(self.test_out + "/warnings.log",'r',encoding='ISO-8859-1').read()
-        failed_warn =  len(warnings)!=0
-        if failed_warn:
-            msg += (warnings,)
+        # Path to the warnings log file
+        log_file_path = self.test_out + "/warnings.log"
+        # Retrieve expected warning patterns from the test configuration
+        expected_warning_patterns = self.config.get('expected_warning_patterns', [])
+        # Check for unexpected warnings
+        unexpected_warnings, missing_warnings = self.check_warnings(log_file_path, expected_warning_patterns)
+        failed_warn = False
+        if unexpected_warnings or missing_warnings:
+            failed_warn = True
+            if unexpected_warnings:
+                msg += ("Unexpected warnings found:\n" + "".join(unexpected_warnings),)
+            if missing_warnings:
+                msg += ("Expected warnings not found:\n" + "".join(missing_warnings),)
 
         if failed_warn or failed_xml or failed_html or failed_qhp or failed_latex or failed_docbook or failed_rtf or failed_xmlxsd:
             testmgr.ok(False,self.test_name,msg)