Add doxygen input filter to strip block comments (facebook#55888)

Summary:
Pull Request resolved: facebook#55888

Adds a doxygen input filter (`input_filters/doxygen_strip_comments.py`) that strips block comments from source files before doxygen parses them.

This prevents doxygen from incorrectly parsing Objective-C code examples (like `interface`, `protocol`) within documentation comments as actual code declarations. For example, a doc comment containing:

```
/**
 * Example:
 *   interface RCT_EXTERN_MODULE(MyModule, NSObject)
 *   end
 */
```

Was being parsed by doxygen as an actual interface declaration, resulting in malformed output like `interface RCT_EXTERN_MODULE {}` in the API snapshot.

The filter preserves line numbers by replacing comment content with the equivalent number of newlines, ensuring error messages remain accurate.

Changelog:
[Internal]

Reviewed By: cortinico

Differential Revision: D94538938

fbshipit-source-id: 4abbb9ed80cc1ca8eb8f128a4f06a0f4d2bc70d3

Author: coado

packages/react-native/.doxygen.config.template

@@ -1123,7 +1123,7 @@ IMAGE_PATH             =
 # need to set EXTENSION_MAPPING for the extension otherwise the files are not
 # properly processed by Doxygen.
 
-INPUT_FILTER           =
+INPUT_FILTER           = ${DOXYGEN_INPUT_FILTER}
 
 # The FILTER_PATTERNS tag can be used to specify filters on a per file pattern
 # basis. Doxygen will compare the file name with each pattern and apply the

scripts/cxx-api/input_filters/doxygen_strip_comments.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env fbpython
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Doxygen input filter to strip block comments from source files.
+
+This prevents Doxygen from incorrectly parsing code examples within
+documentation comments as actual code declarations (e.g., @interface,
+@protocol examples in doc comments being parsed as real interfaces).
+
+Usage in doxygen config:
+    INPUT_FILTER = "python3 /path/to/doxygen_strip_comments.py"
+"""
+
+import re
+import sys
+
+
+def strip_block_comments(content: str) -> str:
+    """
+    Remove all block comments (/* ... */ and /** ... */) from content.
+    Preserves line count by replacing comment content with newlines.
+    """
+
+    def replace_with_newlines(match: re.Match) -> str:
+        # Count newlines in original comment to preserve line numbers
+        newline_count = match.group().count("\n")
+        return "\n" * newline_count
+
+    # Pattern to match block comments (non-greedy)
+    comment_pattern = re.compile(r"/\*[\s\S]*?\*/")
+
+    return comment_pattern.sub(replace_with_newlines, content)
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: doxygen_strip_comments.py <filename>", file=sys.stderr)
+        sys.exit(1)
+
+    filename = sys.argv[1]
+
+    try:
+        with open(filename, "r", encoding="utf-8", errors="replace") as f:
+            content = f.read()
+
+        filtered = strip_block_comments(content)
+        print(filtered, end="")
+    except Exception as e:
+        # On error, output original content to not break the build
+        print(f"Warning: Filter error for {filename}: {e}", file=sys.stderr)
+        with open(filename, "r", encoding="utf-8", errors="replace") as f:
+            print(f.read(), end="")
+
+
+if __name__ == "__main__":
+    main()

scripts/cxx-api/manual_test/.doxygen.config.template

@@ -1122,7 +1122,7 @@ IMAGE_PATH             =
 # need to set EXTENSION_MAPPING for the extension otherwise the files are not
 # properly processed by Doxygen.
 
-INPUT_FILTER           =
+INPUT_FILTER           = ${DOXYGEN_INPUT_FILTER}
 
 # The FILTER_PATTERNS tag can be used to specify filters on a per file pattern
 # basis. Doxygen will compare the file name with each pattern and apply the

scripts/cxx-api/parser/__main__.py

@@ -33,6 +33,7 @@ def build_doxygen_config(
     include_directories: list[str] = None,
     exclude_patterns: list[str] = None,
     definitions: dict[str, str | int] = None,
+    input_filter: str = None,
 ) -> None:
     if include_directories is None:
         include_directories = []
@@ -53,6 +54,8 @@ def build_doxygen_config(
         ]
     )
 
+    input_filter_str = input_filter if input_filter else ""
+
     # read the template file
     with open(os.path.join(directory, ".doxygen.config.template")) as f:
         template = f.read()
@@ -62,6 +65,7 @@ def build_doxygen_config(
         template.replace("${INPUTS}", include_directories_str)
         .replace("${EXCLUDE_PATTERNS}", exclude_patterns_str)
         .replace("${PREDEFINED}", definitions_str)
+        .replace("${DOXYGEN_INPUT_FILTER}", input_filter_str)
     )
 
     # write the config file
@@ -77,6 +81,7 @@ def build_snapshot_for_view(
     definitions: dict[str, str | int],
     output_dir: str,
     verbose: bool = True,
+    input_filter: str = None,
 ) -> None:
     if verbose:
         print(f"Generating API view: {api_view}")
@@ -87,6 +92,7 @@ def build_snapshot_for_view(
         include_directories=include_directories,
         exclude_patterns=exclude_patterns,
         definitions=definitions,
+        input_filter=input_filter,
     )
 
     # If there is already a doxygen output directory, delete it
@@ -188,6 +194,17 @@ def main():
     if verbose and args.codegen_path:
         print(f"Codegen output path: {os.path.abspath(args.codegen_path)}")
 
+    input_filter_path = os.path.join(
+        get_react_native_dir(),
+        "scripts",
+        "cxx-api",
+        "input_filters",
+        "doxygen_strip_comments.py",
+    )
+    input_filter = None
+    if os.path.exists(input_filter_path):
+        input_filter = f"python3 {input_filter_path}"
+
     # Parse config file
     config_path = os.path.join(
         get_react_native_dir(), "scripts", "cxx-api", "config.yml"
@@ -219,6 +236,7 @@ def build_snapshots(output_dir: str, verbose: bool) -> None:
                 definitions={},
                 output_dir=output_dir,
                 verbose=verbose,
+                input_filter=input_filter,
             )
 
             if verbose:
@@ -245,7 +263,3 @@ def build_snapshots(output_dir: str, verbose: bool) -> None:
             )
         )
         build_snapshots(output_dir, verbose=True)
-
-
-if __name__ == "__main__":
-    main()

scripts/cxx-api/tests/snapshots/.doxygen.config.template

@@ -1122,7 +1122,7 @@ IMAGE_PATH             =
 # need to set EXTENSION_MAPPING for the extension otherwise the files are not
 # properly processed by Doxygen.
 
-INPUT_FILTER           =
+INPUT_FILTER           = ${DOXYGEN_INPUT_FILTER}
 
 # The FILTER_PATTERNS tag can be used to specify filters on a per file pattern
 # basis. Doxygen will compare the file name with each pattern and apply the

scripts/cxx-api/tests/snapshots/should_not_parse_interface_from_doc_comment/snapshot.api

@@ -0,0 +1,3 @@
+interface RCTRealInterface {
+  public virtual void realMethod();
+}

scripts/cxx-api/tests/snapshots/should_not_parse_interface_from_doc_comment/test.h

@@ -0,0 +1,18 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Example of how to use this module:
+ *
+ *   @interface RCT_EXTERN_MODULE(MyModule, NSObject)
+ *   @end
+ */
+@interface RCTRealInterface
+
+- (void)realMethod;
+
+@end

scripts/cxx-api/tests/test_input_filters.py

@@ -0,0 +1,71 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+from __future__ import annotations
+
+import unittest
+
+from ..input_filters.doxygen_strip_comments import strip_block_comments
+
+
+class TestDoxygenStripComments(unittest.TestCase):
+    def test_strips_single_line_block_comment(self):
+        content = "/* comment */ code"
+        result = strip_block_comments(content)
+        self.assertEqual(result, " code")
+
+    def test_strips_multiline_block_comment(self):
+        content = """/**
+ * Doc comment
+ * with multiple lines
+ */
+@interface RealInterface
+@end"""
+        result = strip_block_comments(content)
+        # Should preserve 4 newlines (one for each line in the comment)
+        self.assertEqual(
+            result,
+            """\n\n\n
+@interface RealInterface
+@end""",
+        )
+
+    def test_preserves_code_outside_comments(self):
+        content = """@interface MyClass
+- (void)method;
+@end"""
+        result = strip_block_comments(content)
+        self.assertEqual(result, content)
+
+    def test_strips_comment_with_objc_keywords(self):
+        """This is the main use case - stripping comments that contain @interface etc."""
+        content = """/**
+ * Example:
+ *   @interface RCT_EXTERN_MODULE(MyModule, NSObject)
+ *   @end
+ */
+@interface RealInterface
+@end"""
+        result = strip_block_comments(content)
+        self.assertNotIn("RCT_EXTERN_MODULE", result)
+        self.assertIn("@interface RealInterface", result)
+
+    def test_handles_multiple_comments(self):
+        content = """/* first */ code /* second */ more"""
+        result = strip_block_comments(content)
+        self.assertEqual(result, " code  more")
+
+    def test_handles_empty_content(self):
+        result = strip_block_comments("")
+        self.assertEqual(result, "")
+
+    def test_handles_no_comments(self):
+        content = "just code without comments"
+        result = strip_block_comments(content)
+        self.assertEqual(result, content)
+
+
+if __name__ == "__main__":
+    unittest.main()

scripts/cxx-api/tests/test_snapshots.py

@@ -49,18 +49,21 @@ def _assert_text_equal_with_diff(
     tc.fail(diff)
 
 
-def _get_doxygen_bin() -> str:
-    return os.environ.get("DOXYGEN_BIN", "doxygen")
-
-
-def _generate_doxygen_api(case_dir_path: str, doxygen_config_path: str) -> None:
+def _generate_doxygen_api(
+    case_dir_path: str, doxygen_config_path: str, filter_script_path: str | None = None
+) -> None:
     """Run doxygen to generate XML API documentation."""
-    doxygen_bin = _get_doxygen_bin()
+    env = os.environ.copy()
+    if filter_script_path:
+        env["DOXYGEN_INPUT_FILTER"] = f"python3 {filter_script_path}"
+
+    doxygen_bin = env.get("DOXYGEN_BIN", "doxygen")
     result = subprocess.run(
         [doxygen_bin, doxygen_config_path],
         cwd=case_dir_path,
         capture_output=True,
         text=True,
+        env=env,
     )
     if result.returncode != 0:
         raise RuntimeError(f"Doxygen failed: {result.stderr}")
@@ -101,8 +104,22 @@ def _test(self: unittest.TestCase) -> None:
             case_dir_path = tests_root_path / case_dir.name
             doxygen_config_path = tests_root_path / ".doxygen.config.template"
 
+            # Find the filter script in the package resources
+            pkg_root = ir.files(__package__ if __package__ else "__main__")
+            filter_script = (
+                pkg_root.parent / "input_filters" / "doxygen_strip_comments.py"
+            )
+
+            # Get real filesystem path for filter script if it exists
+            filter_script_path = None
+            if filter_script.is_file():
+                with ir.as_file(filter_script) as fs_path:
+                    filter_script_path = str(fs_path)
+
             # Run doxygen to generate the XML
-            _generate_doxygen_api(str(case_dir_path), str(doxygen_config_path))
+            _generate_doxygen_api(
+                str(case_dir_path), str(doxygen_config_path), filter_script_path
+            )
 
             # Parse the generated XML
             xml_dir = case_dir_path / "api" / "xml"