From 6558d0d374961229224c2d74c136ce4078938e3d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dawid=20Ma=C5=82ecki?= Date: Thu, 5 Mar 2026 07:21:42 -0800 Subject: [PATCH] Add doxygen input filter to strip block comments (#55888) Summary: Pull Request resolved: https://github.com/facebook/react-native/pull/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 --- .../react-native/.doxygen.config.template | 2 +- .../input_filters/doxygen_strip_comments.py | 60 ++++++++++++++++ .../manual_test/.doxygen.config.template | 2 +- scripts/cxx-api/parser/__main__.py | 22 ++++-- .../tests/snapshots/.doxygen.config.template | 2 +- .../snapshot.api | 3 + .../test.h | 18 +++++ scripts/cxx-api/tests/test_input_filters.py | 71 +++++++++++++++++++ scripts/cxx-api/tests/test_snapshots.py | 31 ++++++-- 9 files changed, 197 insertions(+), 14 deletions(-) create mode 100755 scripts/cxx-api/input_filters/doxygen_strip_comments.py create mode 100644 scripts/cxx-api/tests/snapshots/should_not_parse_interface_from_doc_comment/snapshot.api create mode 100644 scripts/cxx-api/tests/snapshots/should_not_parse_interface_from_doc_comment/test.h create mode 100644 scripts/cxx-api/tests/test_input_filters.py diff --git a/packages/react-native/.doxygen.config.template b/packages/react-native/.doxygen.config.template index d7f5cd197aa..4f982c734bc 100644 --- a/packages/react-native/.doxygen.config.template +++ b/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 diff --git a/scripts/cxx-api/input_filters/doxygen_strip_comments.py b/scripts/cxx-api/input_filters/doxygen_strip_comments.py new file mode 100755 index 00000000000..d379f7d1c9d --- /dev/null +++ b/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 ", 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() diff --git a/scripts/cxx-api/manual_test/.doxygen.config.template b/scripts/cxx-api/manual_test/.doxygen.config.template index 15952235cae..cac0975942a 100644 --- a/scripts/cxx-api/manual_test/.doxygen.config.template +++ b/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 diff --git a/scripts/cxx-api/parser/__main__.py b/scripts/cxx-api/parser/__main__.py index 96673ad2dfe..2d7a8cfd52c 100644 --- a/scripts/cxx-api/parser/__main__.py +++ b/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 main(): definitions={}, output_dir=output_dir, verbose=verbose, + input_filter=input_filter, ) if verbose: @@ -245,7 +263,3 @@ def main(): ) ) build_snapshots(output_dir, verbose=True) - - -if __name__ == "__main__": - main() diff --git a/scripts/cxx-api/tests/snapshots/.doxygen.config.template b/scripts/cxx-api/tests/snapshots/.doxygen.config.template index 50d418c394f..f5f56836001 100644 --- a/scripts/cxx-api/tests/snapshots/.doxygen.config.template +++ b/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 diff --git a/scripts/cxx-api/tests/snapshots/should_not_parse_interface_from_doc_comment/snapshot.api b/scripts/cxx-api/tests/snapshots/should_not_parse_interface_from_doc_comment/snapshot.api new file mode 100644 index 00000000000..e5a54251d3c --- /dev/null +++ b/scripts/cxx-api/tests/snapshots/should_not_parse_interface_from_doc_comment/snapshot.api @@ -0,0 +1,3 @@ +interface RCTRealInterface { + public virtual void realMethod(); +} diff --git a/scripts/cxx-api/tests/snapshots/should_not_parse_interface_from_doc_comment/test.h b/scripts/cxx-api/tests/snapshots/should_not_parse_interface_from_doc_comment/test.h new file mode 100644 index 00000000000..3ffcc2f8474 --- /dev/null +++ b/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 diff --git a/scripts/cxx-api/tests/test_input_filters.py b/scripts/cxx-api/tests/test_input_filters.py new file mode 100644 index 00000000000..2aa3bf50881 --- /dev/null +++ b/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() diff --git a/scripts/cxx-api/tests/test_snapshots.py b/scripts/cxx-api/tests/test_snapshots.py index c78687904d4..4b21fcd728f 100644 --- a/scripts/cxx-api/tests/test_snapshots.py +++ b/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 _make_case_test(case_dir: Traversable, tests_root: Traversable): 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"