Qualify type arguments based on scope context (#55697)

Summary:
Pull Request resolved: https://github.com/facebook/react-native/pull/55697

Changelog: [Internal]

Implements fallback name qualification for cases where doxygen doesn't extract the full qualified name, and instead passes on the string it found in the header file.

- Adds type_qualification.py with qualify_type_str(), qualify_arguments(), and qualify_parsed_type()
- Updates member.py with close() methods for VariableMember, FunctionMember, and TypedefMember to apply type qualification
- Updates main.py with get_doxygen_params() to extract structured parameter info

Reviewed By: cipolleschi

Differential Revision: D94077825

fbshipit-source-id: 2265f5573164af1af129014082fc44fb8fceb135
This commit is contained in:
Jakub Piasecki authored and meta-codesync[bot] committed 2026-02-25 11:16:36 -08:00
1 parent 357dd6b3ec
commit f013533487
25 files changed
+503 -12

No files matched your search

+33 -1
View File
@@ -20,7 +20,7 @@ from .member import (
from .scope import StructLikeScopeKind
from .snapshot import Snapshot
from .template import Template
from .utils import parse_qualified_path
from .utils import Argument, extract_qualifiers, parse_qualified_path
def resolve_ref_text_name(type_def: compound.refTextType) -> str:
@@ -206,6 +206,35 @@ def get_variable_member(
)
def get_doxygen_params(
function_def: compound.MemberdefType,
) -> list[tuple[str | None, str, str | None, str | None]] | None:
"""
Extract structured parameter information from doxygen <param> elements.
Returns a list of Argument tuples (qualifiers, type, name, default_value),
or None if no <param> elements are available.
"""
params = function_def.param
if not params:
return None
arguments: list[Argument] = []
for param in params:
param_type = (
resolve_ref_text_name(param.get_type()).strip() if param.get_type() else ""
)
param_name = param.declname or param.defname or None
param_default = (
resolve_ref_text_name(param.defval).strip() if param.defval else None
)
qualifiers, core_type = extract_qualifiers(param_type)
arguments.append((qualifiers, core_type, param_name, param_default))
return arguments
def get_function_member(
function_def: compound.MemberdefType,
visibility: str,
@@ -222,6 +251,8 @@ def get_function_member(
or function_def.get_virt() == "pure-virtual"
)
doxygen_params = get_doxygen_params(function_def)
function = FunctionMember(
function_name,
function_type,
@@ -229,6 +260,7 @@ def get_function_member(
function_arg_string,
function_virtual,
is_static,
doxygen_params,
)
function.add_template(get_template_params(function_def))
+9 -6
View File
@@ -16,6 +16,9 @@ from .utils import (
parse_arg_string,
parse_function_pointer_argstring,
parse_type_with_argstrings,
qualify_arguments,
qualify_parsed_type,
qualify_type_str,
)
if TYPE_CHECKING:
@@ -102,8 +105,8 @@ class VariableMember(Member):
self._parsed_type: list[str | list[Argument]] = parse_type_with_argstrings(type)
def close(self, scope: Scope):
# TODO: handle unqualified references
pass
self._fp_arguments = qualify_arguments(self._fp_arguments, scope)
self._parsed_type = qualify_parsed_type(self._parsed_type, scope)
def _is_function_pointer(self) -> bool:
"""Check if this variable is a function pointer type."""
@@ -179,8 +182,8 @@ class FunctionMember(Member):
self.is_override = self.modifiers.is_override
def close(self, scope: Scope):
# TODO: handle unqualified references
pass
self.type = qualify_type_str(self.type, scope)
self.arguments = qualify_arguments(self.arguments, scope)
def to_string(
self,
@@ -255,8 +258,8 @@ class TypedefMember(Member):
self.type: str = type
def close(self, scope: Scope):
# TODO: handle unqualified references
pass
self._fp_arguments = qualify_arguments(self._fp_arguments, scope)
self._parsed_type = qualify_parsed_type(self._parsed_type, scope)
def _is_function_pointer(self) -> bool:
"""Check if this typedef is a function pointer type."""
+58
View File
@@ -178,6 +178,64 @@ class Scope(Generic[ScopeKindT]):
angle_idx = name.find("<")
return name[:angle_idx] if angle_idx != -1 else name
def qualify_name(self, name: str | None) -> str | None:
"""
Qualify a name with the relevant scope if possible.
Handles template arguments by stripping them for lookup but preserving
them in the output.
"""
if not name:
return None
path = parse_qualified_path(name)
if not path:
return None
current_scope = self
# Walk up to find a scope that contains the first path segment
base_first = self._get_base_name(path[0])
while (
current_scope is not None and base_first not in current_scope.inner_scopes
):
current_scope = current_scope.parent_scope
if current_scope is None:
return None
# Remember the scope where we found the first segment — its qualified
# name is the prefix that must precede the matched path segments.
anchor_scope = current_scope
# Walk down through the path, tracking matched segments with original template args
matched_segments: list[str] = []
for i, path_segment in enumerate(path):
base_name = self._get_base_name(path_segment)
if base_name in current_scope.inner_scopes:
matched_segments.append(path_segment)
current_scope = current_scope.inner_scopes[base_name]
elif any(m.name == base_name for m in current_scope._members):
# Found as a member, assume following segments exist in the scope
prefix = "::".join(matched_segments)
suffix = "::".join(path[i:])
anchor_prefix = anchor_scope.get_qualified_name()
if prefix:
if anchor_prefix:
return f"{anchor_prefix}::{prefix}::{suffix}"
return f"{prefix}::{suffix}"
else:
if anchor_prefix:
return f"{anchor_prefix}::{suffix}"
return suffix
else:
return None
# Return qualified name with preserved template arguments
prefix = anchor_scope.get_qualified_name()
if prefix:
return f"{prefix}::{'::'.join(matched_segments)}"
else:
return "::".join(matched_segments)
def add_member(self, member: Member | None) -> None:
"""
Add a member to the scope.
View File
Whitespace-only changes.
+4
View File
@@ -14,6 +14,7 @@ from .argument_parsing import (
parse_type_with_argstrings,
)
from .qualified_path import parse_qualified_path
from .type_qualification import qualify_arguments, qualify_parsed_type, qualify_type_str
__all__ = [
"Argument",
@@ -25,4 +26,7 @@ __all__ = [
"parse_function_pointer_argstring",
"parse_qualified_path",
"parse_type_with_argstrings",
"qualify_arguments",
"qualify_parsed_type",
"qualify_type_str",
]
@@ -0,0 +1,148 @@
# 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
from typing import TYPE_CHECKING
from .argument_parsing import _find_matching_angle, _split_arguments, Argument
if TYPE_CHECKING:
from .scope import Scope
def qualify_arguments(arguments: list[Argument], scope: Scope) -> list[Argument]:
"""Qualify type and default-value references in a list of arguments."""
result: list[Argument] = []
for qualifiers, arg_type, name, default in arguments:
qualified_type = qualify_type_str(arg_type, scope)
qualified_default = scope.qualify_name(default)
if qualified_default is not None:
default = qualified_default
result.append((qualifiers, qualified_type, name, default))
return result
def qualify_type_str(type_str: str, scope: Scope) -> str:
"""Qualify a type string, handling trailing decorators (*, &, &&, etc.)."""
if not type_str:
return type_str
# Handle template arguments first: qualify types inside angle brackets
angle_start = type_str.find("<")
if angle_start != -1:
angle_end = _find_matching_angle(type_str, angle_start)
if angle_end != -1:
prefix = type_str[:angle_start]
template_args = type_str[angle_start + 1 : angle_end]
suffix = type_str[angle_end + 1 :]
# Qualify the prefix (outer type before the template)
qualified_prefix = scope.qualify_name(prefix) or prefix
# Split template arguments and qualify each one
args = _split_arguments(template_args)
qualified_args = [qualify_type_str(arg.strip(), scope) for arg in args]
qualified_template = "< " + ", ".join(qualified_args) + " >"
# Recursively qualify the suffix (handles nested templates, pointers, etc.)
qualified_suffix = qualify_type_str(suffix, scope) if suffix else ""
return qualified_prefix + qualified_template + qualified_suffix
# Try qualifying the entire string (handles simple cases without templates)
qualified = scope.qualify_name(type_str)
if qualified is not None:
return qualified
# Handle function pointer/reference declarator prefix: "Type(*" or "Type(&"
for declarator in ("(*", "(&"):
if type_str.endswith(declarator):
prefix = type_str[: -len(declarator)].rstrip()
if prefix:
q = qualify_type_str(prefix, scope)
if q != prefix:
return q + declarator
return type_str
# Strip trailing pointer/reference/const decorators and try again.
# Loop so that mixed sequences like "Type *const" or "Type const*" are
# fully peeled regardless of order.
stripped = type_str.rstrip()
suffix = ""
changed = True
while changed:
changed = False
while stripped and stripped[-1] in ("*", "&"):
suffix = stripped[-1] + suffix
stripped = stripped[:-1].rstrip()
changed = True
# Handle trailing "const" (possibly preceded by space or pointer)
if stripped.endswith(" const") or stripped.endswith("*const"):
is_after_ptr = stripped.endswith("*const")
suffix = "const " + suffix
stripped = stripped[: -len("const")].rstrip()
if is_after_ptr:
# Re-enter loop to peel the '*' that preceded "const"
pass
changed = True
if suffix and stripped:
qualified = scope.qualify_name(stripped)
if qualified is not None:
suffix = suffix.rstrip()
if "const" in suffix:
return qualified + " " + suffix
return qualified + suffix
return type_str
def _qualify_text_before_args(text: str, scope: Scope) -> str:
"""Qualify the trailing return-type in a text segment that precedes an arg list.
When ``parse_type_with_argstrings`` splits ``"std::function< Result(Param)"``
the text segment ``"std::function< Result"`` contains a return type at the
end that must be qualified independently.
"""
# Try qualifying the whole text first (covers simple "Result" etc.)
qualified = qualify_type_str(text, scope)
if qualified != text:
return qualified
# Try qualifying just the last whitespace-delimited token
stripped = text.rstrip()
last_space = stripped.rfind(" ")
if last_space == -1:
return text
prefix = stripped[: last_space + 1]
last_token = stripped[last_space + 1 :]
qualified_token = scope.qualify_name(last_token)
if qualified_token is not None:
return prefix + qualified_token
return text
def qualify_parsed_type(
segments: list[str | list[Argument]], scope: Scope
) -> list[str | list[Argument]]:
"""Qualify references inside parsed-type segments."""
result: list[str | list[Argument]] = []
for i, seg in enumerate(segments):
if isinstance(seg, list):
result.append(qualify_arguments(seg, scope))
else:
# If the next segment is a parsed argument list, the end of this
# text likely contains a return type that needs qualification.
next_is_args = i + 1 < len(segments) and isinstance(segments[i + 1], list)
if next_is_args:
result.append(_qualify_text_before_args(seg, scope))
else:
result.append(qualify_type_str(seg, scope))
return result
@@ -2,18 +2,18 @@ class test::Clss {
public virtual void fn16() = 0;
public void fn0(int32_t arg1);
public void fn1(int32_t arg1, int32_t arg2);
public void fn2(std::function< int32_t(int32_t)> arg1);
public void fn3(std::function< int32_t(int32_t)> arg1, std::function< int32_t(int32_t, int32_t)> arg2);
public void fn2(std::function< int32_t(int32_t) > arg1);
public void fn3(std::function< int32_t(int32_t) > arg1, std::function< int32_t(int32_t, int32_t) > arg2);
public void fn4(std::map< std::string, int > m);
public void fn5(std::unordered_map< K, std::vector< V > > m);
public void fn6(std::tuple< int, float, std::string > t);
public void fn7(std::vector< std::vector< std::pair< int, int > > > v);
public void fn8(std::map< K, std::function< void(A, B)> > m);
public void fn8(std::map< K, std::function< void(A, B) > > m);
public void fn9(int(*)(int, int) callback);
public void fn10(void(*)(const char *, size_t) handler);
public void fn11(int(*(*)(int))(double) fp);
public void fn11(int(*(*fp)(int))(double));
public void fn12(int x = 5, std::string s = "default");
public void fn13(std::function< void()> f = nullptr);
public void fn13(std::function< void() > f = nullptr);
public void fn14(std::vector< int > v = {1, 2, 3});
public void fn15() noexcept;
public void fn17() = default;
@@ -0,0 +1,6 @@
struct test::Param {
}
typedef void(*test::FreeFnPtr)(test::Param);
using test::FreeCallback = void(test::Param);
void test::freeFunction(test::Param p);
@@ -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.
*/
#pragma once
namespace test {
struct Param {};
void freeFunction(Param p);
typedef void (*FreeFnPtr)(Param);
using FreeCallback = void(Param);
} // namespace test
@@ -0,0 +1,8 @@
struct test::Container {
public void doConst(const test::Param& p);
public void doMultiple(test::Param a, test::Param b, int x);
public void doSomething(test::Param p);
}
struct test::Param {
}
@@ -0,0 +1,20 @@
/*
* 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.
*/
#pragma once
namespace test {
struct Param {};
struct Container {
void doSomething(Param p);
void doConst(const Param &p);
void doMultiple(Param a, Param b, int x);
};
} // namespace test
@@ -0,0 +1,8 @@
facebook::yoga::Result facebook::react::getResult(facebook::yoga::Node node, int flags);
void facebook::react::processNode(facebook::yoga::Node node);
struct facebook::yoga::Node {
}
struct facebook::yoga::Result {
}
@@ -0,0 +1,27 @@
/*
* 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.
*/
#pragma once
namespace facebook {
namespace yoga {
struct Node {};
struct Result {};
} // namespace yoga
namespace react {
void processNode(yoga::Node node);
yoga::Result getResult(yoga::Node node, int flags);
} // namespace react
} // namespace facebook
@@ -0,0 +1 @@
void test::doSomething(const Node *const node, int x);
@@ -0,0 +1,16 @@
/*
* 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.
*/
#pragma once
namespace test {
struct Node;
void doSomething(const Node *const node, int x);
} // namespace test
@@ -0,0 +1,6 @@
struct test::Container {
public typedef void(*FnPtr)(test::Param, int);
}
struct test::Param {
}
@@ -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.
*/
#pragma once
namespace test {
struct Param {};
struct Container {
typedef void (*FnPtr)(Param, int);
};
} // namespace test
@@ -0,0 +1,10 @@
struct test::Container {
public using Callback = void(test::Param);
public using Processor = test::Result(test::Param, int);
}
struct test::Param {
}
struct test::Result {
}
@@ -0,0 +1,20 @@
/*
* 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.
*/
#pragma once
namespace test {
struct Param {};
struct Result {};
struct Container {
using Callback = void(Param);
using Processor = Result(Param, int);
};
} // namespace test
@@ -0,0 +1,6 @@
struct test::Container {
public void(*handler)(test::Param, int);
}
struct test::Param {
}
@@ -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.
*/
#pragma once
namespace test {
struct Param {};
struct Container {
void (*handler)(Param, int);
};
} // namespace test
@@ -0,0 +1,13 @@
struct test::Container {
public std::function< test::Result(test::Param, int)> processor;
public std::function< void(const test::Param&, test::Result)> multiRef;
public std::function< void(test::Param)> simpleCallback;
public test::Result(*fnPtrReturn)(const test::Param&);
public void(*fnPtr)(test::Param, int);
}
struct test::Param {
}
struct test::Result {
}
@@ -0,0 +1,25 @@
/*
* 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.
*/
#pragma once
#include <functional>
namespace test {
struct Param {};
struct Result {};
struct Container {
std::function<void(Param)> simpleCallback;
std::function<Result(Param, int)> processor;
std::function<void(const Param &, Result)> multiRef;
void (*fnPtr)(Param, int);
Result (*fnPtrReturn)(const Param &);
};
} // namespace test
@@ -0,0 +1,7 @@
struct test::Container {
public const test::Param constField;
public test::Param field;
}
struct test::Param {
}
@@ -0,0 +1,19 @@
/*
* 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.
*/
#pragma once
namespace test {
struct Param {};
struct Container {
Param field;
const Param constField;
};
} // namespace test