Fix issue with parsing lightweight objective-c generics (#55979)

Summary:
Pull Request resolved: #55979

Fixes issue with parsing lightweight objective-c generics. Doxygen produces malformed xml output due to incorrect handling of interfaces such as:

```obj-c
interface Foo<T> : NSObject
end
```

The solution is to encode the interface into the form of `interface Foo__GENERICS_T_ENDGENERICS`, then produce the snapshot and finally decode it back to `interface Foo<T>`.

Changelog:
[Internal]

Reviewed By: cipolleschi

Differential Revision: D95567196

fbshipit-source-id: c8ae97f99e893ecd48ded21f24a650286d708c60

Author: coado

scripts/cxx-api/input_filters/handle_objc_interface_generics.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.
+
+import re
+
+
+# Sentinel tokens used to encode ObjC generics into the class name so they
+# survive Doxygen processing.  The parser decodes them back into angle-bracket
+# syntax when building the snapshot.
+GENERICS_START = "__GENERICS__"
+GENERICS_END = "__ENDGENERICS__"
+GENERICS_COMMA = "__COMMA__"
+
+
+def encode_objc_interface_generics(content: str) -> str:
+    """
+    Encode ObjC lightweight generic type parameters on @interface declarations
+    into the class name so Doxygen doesn't misinterpret them as C++ templates.
+
+    Doxygen treats angle brackets in ``@interface Foo<T> : Base`` as template
+    syntax, which corrupts the XML output (wrong base class, __pad0__
+    artifacts, property attribute leaks).  We encode ``<T>`` into the class
+    name as ``__GENERICS__T__ENDGENERICS__`` so the name remains a valid C
+    identifier.  The parser later decodes it back to ``Foo<T>``.
+
+    Only generics *immediately* after the class name are affected.  Protocol
+    conformances like ``Base <Protocol>`` (with a space) are left untouched.
+    """
+
+    def _encode(match: re.Match) -> str:
+        prefix = match.group(1)  # "@interface ClassName"
+        params = match.group(2)  # "K, V"
+        parts = [p.strip() for p in params.split(",")]
+        encoded = GENERICS_COMMA.join(parts)
+        return f"{prefix}{GENERICS_START}{encoded}{GENERICS_END}"
+
+    # Match @interface followed by a name immediately followed by <...> (no space).
+    # This distinguishes generics (no space) from protocol conformance (space before <).
+    pattern = re.compile(r"(@interface\s+\w+)<([^>]+)>")
+    return pattern.sub(_encode, content)
+
+
+def decode_objc_generics(name: str) -> str:
+    """
+    Decode an encoded class name back to its original generic syntax.
+
+    ``Foo__GENERICS__K__COMMA__V__ENDGENERICS__`` → ``Foo<K, V>``
+    """
+    match = re.match(
+        rf"^(.+?){re.escape(GENERICS_START)}(.+?){re.escape(GENERICS_END)}$",
+        name,
+    )
+    if not match:
+        return name
+    class_name = match.group(1)
+    params = match.group(2).replace(GENERICS_COMMA, ", ")
+    return f"{class_name}<{params}>"

scripts/cxx-api/input_filters/main.py

@@ -9,6 +9,7 @@
 
 sys.path.insert(0, os.path.dirname(__file__))
 
+from handle_objc_interface_generics import encode_objc_interface_generics
 from strip_block_comments import strip_block_comments
 from strip_deprecated_msg import strip_deprecated_msg
 from strip_ns_unavailable import strip_ns_unavailable
@@ -28,6 +29,7 @@ def main():
         filtered = strip_block_comments(content)
         filtered = strip_deprecated_msg(filtered)
         filtered = strip_ns_unavailable(filtered)
+        filtered = encode_objc_interface_generics(filtered)
         print(filtered, end="")
     except Exception as e:
         # On error, output original content to not break the build

scripts/cxx-api/parser/builders.py

@@ -17,6 +17,7 @@
 
 from doxmlparser import compound
 
+from ..input_filters.handle_objc_interface_generics import decode_objc_generics
 from .member import (
     ConceptMember,
     EnumMember,
@@ -510,6 +511,12 @@ def create_interface_scope(
     """
     interface_name = scope_def.compoundname
 
+    # Decode ObjC generics that were encoded by the input filter.
+    # The input filter encodes ``@interface Foo<T>`` as
+    # ``@interface Foo__GENERICS__T__ENDGENERICS__`` so Doxygen can parse it.
+    # We restore the original ``Foo<T>`` name here.
+    interface_name = decode_objc_generics(interface_name)
+
     interface_scope = snapshot.create_interface(interface_name)
     base_classes = get_base_classes(scope_def, base_class=InterfaceScopeKind.Base)
 

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

@@ -0,0 +1,5 @@
+interface RCTMapper<KeyT, ValueT> : public NSObject {
+  public @property (strong) KeyT key;
+  public @property (strong) ValueT value;
+  public virtual void setKey:value:(KeyT key, ValueT value);
+}

scripts/cxx-api/tests/snapshots/should_handle_interface_with_multiple_generics/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.
+ */
+
+@interface RCTMapper<KeyT, ValueT> : NSObject
+
+@property (nonatomic, strong) KeyT key;
+@property (nonatomic, strong) ValueT value;
+- (void)setKey:(KeyT)key value:(ValueT)value;
+
+@end

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

@@ -0,0 +1,5 @@
+interface RCTGenericDelegateSplitter<DelegateT> : public NSObject {
+  public @property (copy) void(^delegateUpdateBlock)(DelegateT _Nullable delegate);
+  public virtual void addDelegate:(DelegateT delegate);
+  public virtual void removeDelegate:(DelegateT delegate);
+}

scripts/cxx-api/tests/snapshots/should_handle_interface_with_single_generic/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.
+ */
+
+@interface RCTGenericDelegateSplitter<DelegateT> : NSObject
+
+@property (nonatomic, copy, nullable) void (^delegateUpdateBlock)(DelegateT _Nullable delegate);
+- (void)addDelegate:(DelegateT)delegate;
+- (void)removeDelegate:(DelegateT)delegate;
+
+@end

scripts/cxx-api/tests/test_input_filters.py

@@ -7,6 +7,10 @@
 
 import unittest
 
+from ..input_filters.handle_objc_interface_generics import (
+    decode_objc_generics,
+    encode_objc_interface_generics,
+)
 from ..input_filters.strip_block_comments import strip_block_comments
 from ..input_filters.strip_deprecated_msg import strip_deprecated_msg
 from ..input_filters.strip_ns_unavailable import strip_ns_unavailable
@@ -208,5 +212,67 @@ def test_handles_leading_whitespace(self):
         self.assertEqual(result, "")
 
 
+class TestEncodeObjcInterfaceGenerics(unittest.TestCase):
+    def test_single_generic_param(self):
+        content = "@interface Foo<T> : NSObject\n@end"
+        result = encode_objc_interface_generics(content)
+        self.assertEqual(
+            result,
+            "@interface Foo__GENERICS__T__ENDGENERICS__ : NSObject\n@end",
+        )
+
+    def test_two_generic_params(self):
+        content = "@interface MyMap<K, V> : NSObject\n@end"
+        result = encode_objc_interface_generics(content)
+        self.assertEqual(
+            result,
+            "@interface MyMap__GENERICS__K__COMMA__V__ENDGENERICS__ : NSObject\n@end",
+        )
+
+    def test_protocol_conformance_not_encoded(self):
+        content = "@interface Foo : NSObject <NSCopying>"
+        result = encode_objc_interface_generics(content)
+        self.assertEqual(result, content)
+
+    def test_interface_without_generics(self):
+        content = "@interface MyClass : NSObject\n- (void)method;\n@end"
+        result = encode_objc_interface_generics(content)
+        self.assertEqual(result, content)
+
+    def test_multiple_interfaces_both_with_generics(self):
+        content = (
+            "@interface Foo<T> : NSObject\n@end\n\n"
+            "@interface Bar<K, V> : NSObject\n@end"
+        )
+        result = encode_objc_interface_generics(content)
+        self.assertIn("__GENERICS__T__ENDGENERICS__", result)
+        self.assertIn("__GENERICS__K__COMMA__V__ENDGENERICS__", result)
+
+
+class TestDecodeObjcGenerics(unittest.TestCase):
+    def test_single_generic_param(self):
+        result = decode_objc_generics("Foo__GENERICS__T__ENDGENERICS__")
+        self.assertEqual(result, "Foo<T>")
+
+    def test_two_generic_params(self):
+        result = decode_objc_generics("MyMap__GENERICS__K__COMMA__V__ENDGENERICS__")
+        self.assertEqual(result, "MyMap<K, V>")
+
+    def test_roundtrip_single_generic(self):
+        content = "@interface Foo<T> : NSObject\n@end"
+        encoded = encode_objc_interface_generics(content)
+        # Extract the encoded class name (between "@interface " and " :")
+        encoded_name = encoded.split("@interface ")[1].split(" :")[0]
+        decoded_name = decode_objc_generics(encoded_name)
+        self.assertEqual(decoded_name, "Foo<T>")
+
+    def test_roundtrip_multiple_generics(self):
+        content = "@interface MyMap<K, V> : NSObject\n@end"
+        encoded = encode_objc_interface_generics(content)
+        encoded_name = encoded.split("@interface ")[1].split(" :")[0]
+        decoded_name = decode_objc_generics(encoded_name)
+        self.assertEqual(decoded_name, "MyMap<K, V>")
+
+
 if __name__ == "__main__":
     unittest.main()