Extract member specializations from name

Summary:
Changelog: [Internal]

Updates the C++ API snapshot generator to extract specializations from name when a member is created, instead of relying on the one stored in the name string.

It also makes out-of-class definitions of members to be skipped in the snapshot as those were essentially duplicated between their declaration inside the class, and the initialization outside of it.

Differential Revision: D96303740

Author: j-piasecki

scripts/cxx-api/parser/main.py

@@ -25,7 +25,7 @@
     get_variable_member,
 )
 from .snapshot import Snapshot
-from .utils import parse_qualified_path
+from .utils import has_scope_resolution_outside_angles, parse_qualified_path
 
 
 def build_snapshot(xml_dir: str) -> Snapshot:
@@ -84,12 +84,22 @@ def build_snapshot(xml_dir: str) -> Snapshot:
                 for section_def in compound_object.sectiondef:
                     if section_def.kind == "var":
                         for variable_def in section_def.memberdef:
+                            # Skip out-of-class definitions (e.g. "Strct<T>::VALUE")
+                            if has_scope_resolution_outside_angles(
+                                variable_def.get_name()
+                            ):
+                                continue
                             is_static = variable_def.static == "yes"
                             namespace_scope.add_member(
                                 get_variable_member(variable_def, "public", is_static)
                             )
                     elif section_def.kind == "func":
                         for function_def in section_def.memberdef:
+                            # Skip out-of-class definitions (e.g. "Strct<T>::convert")
+                            if has_scope_resolution_outside_angles(
+                                function_def.get_name()
+                            ):
+                                continue
                             function_static = function_def.static == "yes"
 
                             if not function_static:

scripts/cxx-api/parser/member/function_member.py

@@ -12,8 +12,8 @@
     format_arguments,
     parse_arg_string,
     qualify_arguments,
-    qualify_template_args_only,
     qualify_type_str,
+    split_specialization,
 )
 from .base import Member, MemberKind
 
@@ -34,7 +34,9 @@ def __init__(
         doxygen_params: list[Argument] | None = None,
         is_constexpr: bool = False,
     ) -> None:
-        super().__init__(name, visibility)
+        base_name, specialization_args = split_specialization(name)
+        super().__init__(base_name, visibility)
+        self.specialization_args: list[str] | None = specialization_args
         self.type: str = type
         self.is_virtual: bool = is_virtual
         self.is_static: bool = is_static
@@ -62,10 +64,16 @@ def member_kind(self) -> MemberKind:
     def close(self, scope: Scope):
         self.type = qualify_type_str(self.type, scope)
         self.arguments = qualify_arguments(self.arguments, scope)
-        # Qualify template arguments in function name for explicit specializations
-        # e.g., "convert<MyType>" -> "convert<ns::MyType>"
-        if "<" in self.name:
-            self.name = qualify_template_args_only(self.name, scope)
+        if self.specialization_args is not None:
+            self.specialization_args = [
+                qualify_type_str(arg, scope) for arg in self.specialization_args
+            ]
+
+    def _get_qualified_name(self, qualification: str | None) -> str:
+        name = self.name
+        if self.specialization_args is not None:
+            name = f"{name}<{', '.join(self.specialization_args)}>"
+        return f"{qualification}::{name}" if qualification else name
 
     def to_string(
         self,

scripts/cxx-api/parser/member/variable_member.py

@@ -15,7 +15,8 @@
     parse_type_with_argstrings,
     qualify_arguments,
     qualify_parsed_type,
-    qualify_template_args_only,
+    qualify_type_str,
+    split_specialization,
 )
 from .base import Member, MemberKind, STORE_INITIALIZERS_IN_SNAPSHOT
 
@@ -38,7 +39,9 @@ def __init__(
         argstring: str | None = None,
         is_brace_initializer: bool = False,
     ) -> None:
-        super().__init__(name, visibility)
+        base_name, specialization_args = split_specialization(name)
+        super().__init__(base_name, visibility)
+        self.specialization_args: list[str] | None = specialization_args
         self.type: str = type
         self.value: str | None = value
         self.is_const: bool = is_const
@@ -62,15 +65,21 @@ def member_kind(self) -> MemberKind:
     def close(self, scope: Scope):
         self._fp_arguments = qualify_arguments(self._fp_arguments, scope)
         self._parsed_type = qualify_parsed_type(self._parsed_type, scope)
-        # Qualify template arguments in variable name for explicit specializations
-        # e.g., "default_value<MyType>" -> "default_value<ns::MyType>"
-        if "<" in self.name:
-            self.name = qualify_template_args_only(self.name, scope)
+        if self.specialization_args is not None:
+            self.specialization_args = [
+                qualify_type_str(arg, scope) for arg in self.specialization_args
+            ]
 
     def _is_function_pointer(self) -> bool:
         """Check if this variable is a function pointer type."""
         return self.argstring is not None and self.argstring.startswith(")(")
 
+    def _get_qualified_name(self, qualification: str | None) -> str:
+        name = self.name
+        if self.specialization_args is not None:
+            name = f"{name}<{', '.join(self.specialization_args)}>"
+        return f"{qualification}::{name}" if qualification else name
+
     def to_string(
         self,
         indent: int = 0,

scripts/cxx-api/parser/utils/__init__.py

@@ -9,6 +9,7 @@
     format_arguments,
     format_parsed_type,
     FunctionModifiers,
+    has_scope_resolution_outside_angles,
     parse_arg_string,
     parse_function_pointer_argstring,
     parse_type_with_argstrings,
@@ -22,12 +23,7 @@
     normalize_pointer_spacing,
     resolve_linked_text_name,
 )
-from .type_qualification import (
-    qualify_arguments,
-    qualify_parsed_type,
-    qualify_template_args_only,
-    qualify_type_str,
-)
+from .type_qualification import qualify_arguments, qualify_parsed_type, qualify_type_str
 
 __all__ = [
     "Argument",
@@ -36,6 +32,7 @@
     "format_arguments",
     "format_parsed_type",
     "FunctionModifiers",
+    "has_scope_resolution_outside_angles",
     "InitializerType",
     "normalize_angle_brackets",
     "normalize_pointer_spacing",
@@ -45,7 +42,6 @@
     "parse_type_with_argstrings",
     "qualify_arguments",
     "qualify_parsed_type",
-    "qualify_template_args_only",
     "qualify_type_str",
     "resolve_linked_text_name",
     "split_specialization",

scripts/cxx-api/parser/utils/argument_parsing.py

@@ -116,6 +116,27 @@ def _find_matching_angle(s: str, start: int = 0) -> int:
     return _find_matching_bracket(s, start, "<", ">", ignore_inside="(")
 
 
+def has_scope_resolution_outside_angles(name: str) -> bool:
+    """Check if '::' appears outside angle brackets in a name.
+
+    Returns True for class-prefixed out-of-class definitions
+    (e.g. 'Strct< T >::VALUE') but False when '::' only appears inside
+    template arguments (e.g. 'func<std::string>').
+    """
+    depth = 0
+    i = 0
+    while i < len(name):
+        ch = name[i]
+        if ch == "<":
+            depth += 1
+        elif ch == ">":
+            depth -= 1
+        elif ch == ":" and depth == 0 and i + 1 < len(name) and name[i + 1] == ":":
+            return True
+        i += 1
+    return False
+
+
 def _iter_at_depth_zero(s: str):
     """Iterate over string, yielding (index, char, at_depth_zero) tuples.
 

scripts/cxx-api/parser/utils/type_qualification.py

@@ -31,16 +31,6 @@ def qualify_type_str(type_str: str, scope: Scope) -> str:
     return _qualify_type_str_impl(type_str, scope, qualify_base=True)
 
 
-def qualify_template_args_only(type_str: str, scope: Scope) -> str:
-    """Qualify only template arguments in a type string, leaving the base type unchanged.
-
-    This is useful for class names in template specializations where the base type
-    is already positioned in the correct scope but the template arguments need
-    qualification (e.g., "MyVector< Test >" -> "MyVector< ns::Test >").
-    """
-    return _qualify_type_str_impl(type_str, scope, qualify_base=False)
-
-
 def _qualify_prefix_with_decorators(prefix: str, scope: Scope) -> str:
     """Qualify a template prefix that may have leading const/volatile qualifiers."""
     stripped = prefix.lstrip()

scripts/cxx-api/tests/snapshots/should_handle_free_variable/snapshot.api

@@ -0,0 +1 @@
+int test::helloWorld;

scripts/cxx-api/tests/snapshots/should_handle_free_variable/test.h

@@ -0,0 +1,14 @@
+/*
+ * 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 {
+
+extern int helloWorld;
+
+} // namespace test

scripts/cxx-api/tests/snapshots/should_handle_template_variable/snapshot.api

@@ -1,6 +1,3 @@
-template <typename T>
-const test::Strct<T> test::Strct<T>::VALUE;
-
 template <typename T>
 struct test::Strct {
   public static const test::Strct<T> VALUE;