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
This commit is contained in:
Dawid Małecki authored and meta-codesync[bot] committed 2026-03-05 07:21:42 -08:00
1 parent a6d29d0d38
commit 6558d0d374
9 files changed
+197 -14

No files matched your search

@@ -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
+60
View File
@@ -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()
@@ -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
+18 -4
View File
@@ -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()
@@ -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
@@ -0,0 +1,3 @@
interface RCTRealInterface {
public virtual void realMethod();
}
@@ -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
@@ -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()
+24 -7
View File
@@ -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"