mirror of
https://github.com/facebook/react-native.git
synced 2026-11-18 20:19:07 +00:00
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:
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
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
+3
@@ -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()
|
||||
@@ -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"
|
||||
|
||||
Reference in new issue
Block a user