Add doxygen input filter to strip block comments

Summary:
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.

## Changes

1. **Input Filter**: Added `doxygen_strip_comments.py` that replaces block comments with equivalent newlines to preserve line numbers.

2. **Fixed Empty Snapshots**: Fixed the `__main__.py` to properly pass the `${DOXYGEN_INPUT_FILTER}` placeholder value to doxygen config, which was causing empty snapshot generation.

3. **Normalized Pointer Spacing**: Added `normalize_pointer_spacing()` function to normalize doxygen's output:
   - `NSString *` → `NSString*`
   - `int &` → `int&`
   - `T &&` → `T&&`

4. **Added Snapshot Test**: Created `should_not_parse_interface_from_doc_comment` test case demonstrating the issue.

Differential Revision: D94538938

Author: Dawid Małecki

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

@@ -24,14 +24,15 @@
 
 DOXYGEN_CONFIG_FILE = ".doxygen.config.generated"
 
-RUN_ON_REACT_NATIVE = False
+RUN_ON_REACT_NATIVE = True
 
 
 def build_doxygen_config(
     directory: str,
     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 = []
@@ -52,6 +53,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()
@@ -61,6 +64,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
@@ -75,6 +79,7 @@ def build_snapshot_for_view(
     exclude_patterns: list[str],
     definitions: dict[str, str | int],
     output_dir: str,
+    input_filter: str = None,
 ) -> None:
     print(f"Generating API view: {api_view}")
     # Generate the Doxygen config file
@@ -85,6 +90,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
@@ -178,6 +184,18 @@ def main():
     )
 
     if RUN_ON_REACT_NATIVE:
+        # Find the input filter script
+        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}"
+
         for config in snapshot_configs:
             build_snapshot_for_view(
                 api_view=config.snapshot_name,
@@ -186,6 +204,7 @@ def main():
                 exclude_patterns=config.exclude_patterns,
                 definitions=config.definitions,
                 output_dir=output_dir,
+                input_filter=input_filter,
             )
     else:
         build_snapshot_for_view(

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"