Fix Doxygen merging base classes from primary templates into specializations

Summary:
Doxygen incorrectly merges base classes from primary templates into their partial specializations. In C++, a specialization's inheritance list completely replaces the primary template's, but Doxygen combines both into a single basecompoundref list.

- **Contradictory type traits** — is_optional<std::optional<T>> and is_variant_of_data_types<std::variant<Ts...>> showed inheritance from both std::false_type (primary) and std::true_type (specialization)

- **Duplicate base classes** — Converter<jsi::Object> listed ConverterBase<jsi::Object> twice (once from the primary template after substitution, once from the specialization)

This diff fixes both issues with two complementary mechanisms:

- **Dedup-by-name (Extendable._deduplicate_base_classes)**: removes exact duplicate base classes, keeping the last occurrence. Handles cases where Doxygen's template argument substitution produces identical names.
- **Primary template base subtraction (StructLikeScopeKind._remove_merged_primary_bases)**: for partial specializations, looks up the primary template among sibling scopes and performs count-based subtraction of its bases. Count-based (rather than set-based) subtraction correctly preserves bases that a specialization explicitly re-inherits from the same class as the primary.

Changelog:
[Internal]

Differential Revision: D98291360

Author: coado

scripts/cxx-api/api-snapshots/ReactAndroidDebugCxx.api

@@ -2466,7 +2466,7 @@ class facebook::react::HostPlatformScrollViewProps : public facebook::react::Bas
   public void setProp(const facebook::react::PropsParserContext& context, facebook::react::RawPropsPropNameHash hash, const char* propName, const facebook::react::RawValue& value);
 }
 
-class facebook::react::HostPlatformViewProps : public facebook::react::BaseViewProps, public facebook::react::BaseViewProps {
+class facebook::react::HostPlatformViewProps : public facebook::react::BaseViewProps {
   public HostPlatformViewProps() = default;
   public HostPlatformViewProps() = default;
   public HostPlatformViewProps(const facebook::react::PropsParserContext& context, const facebook::react::HostPlatformViewProps& sourceProps, const facebook::react::RawProps& rawProps);
@@ -10879,7 +10879,7 @@ struct facebook::react::detail::merge_data_types<std::variant<AllowedTypesT...>>
 }
 
 template <CSSDataType... Ts>
-struct facebook::react::detail::is_variant_of_data_types<std::variant<Ts...>> : public std::false_type, public std::true_type {
+struct facebook::react::detail::is_variant_of_data_types<std::variant<Ts...>> : public std::true_type {
 }
 
 template <CSSDataType... AlllowedTypes1T, CSSDataType... AlllowedTypes2T, CSSMaybeCompoundDataType... RestT>
@@ -12476,21 +12476,21 @@ struct facebook::react::bridging::is_optional : public std::false_type {
 }
 
 template <typename T>
-struct facebook::react::bridging::Converter<std::optional<T>> : public facebook::react::bridging::ConverterBase<T>, public facebook::react::bridging::ConverterBase<facebook::jsi::Value> {
+struct facebook::react::bridging::Converter<std::optional<T>> : public facebook::react::bridging::ConverterBase<facebook::jsi::Value> {
   public Converter(facebook::jsi::Runtime& rt, std::optional<T> value);
   public operator std::optional<T>();
 }
 
 template <typename T>
-struct facebook::react::bridging::is_optional<std::optional<T>> : public std::false_type, public std::true_type {
+struct facebook::react::bridging::is_optional<std::optional<T>> : public std::true_type {
 }
 
-struct facebook::react::bridging::Converter<facebook::jsi::Object> : public facebook::react::bridging::ConverterBase<facebook::jsi::Object>, public facebook::react::bridging::ConverterBase<facebook::jsi::Object> {
+struct facebook::react::bridging::Converter<facebook::jsi::Object> : public facebook::react::bridging::ConverterBase<facebook::jsi::Object> {
   public operator jsi::Array();
   public operator jsi::Function();
 }
 
-struct facebook::react::bridging::Converter<facebook::jsi::Value> : public facebook::react::bridging::ConverterBase<facebook::jsi::Value>, public facebook::react::bridging::ConverterBase<facebook::jsi::Value> {
+struct facebook::react::bridging::Converter<facebook::jsi::Value> : public facebook::react::bridging::ConverterBase<facebook::jsi::Value> {
   public operator jsi::Array();
   public operator jsi::Function();
   public operator jsi::Object();

scripts/cxx-api/api-snapshots/ReactAndroidReleaseCxx.api

@@ -2463,7 +2463,7 @@ class facebook::react::HostPlatformScrollViewProps : public facebook::react::Bas
   public void setProp(const facebook::react::PropsParserContext& context, facebook::react::RawPropsPropNameHash hash, const char* propName, const facebook::react::RawValue& value);
 }
 
-class facebook::react::HostPlatformViewProps : public facebook::react::BaseViewProps, public facebook::react::BaseViewProps {
+class facebook::react::HostPlatformViewProps : public facebook::react::BaseViewProps {
   public HostPlatformViewProps() = default;
   public HostPlatformViewProps() = default;
   public HostPlatformViewProps(const facebook::react::PropsParserContext& context, const facebook::react::HostPlatformViewProps& sourceProps, const facebook::react::RawProps& rawProps);
@@ -10706,7 +10706,7 @@ struct facebook::react::detail::merge_data_types<std::variant<AllowedTypesT...>>
 }
 
 template <CSSDataType... Ts>
-struct facebook::react::detail::is_variant_of_data_types<std::variant<Ts...>> : public std::false_type, public std::true_type {
+struct facebook::react::detail::is_variant_of_data_types<std::variant<Ts...>> : public std::true_type {
 }
 
 template <CSSDataType... AlllowedTypes1T, CSSDataType... AlllowedTypes2T, CSSMaybeCompoundDataType... RestT>
@@ -12303,21 +12303,21 @@ struct facebook::react::bridging::is_optional : public std::false_type {
 }
 
 template <typename T>
-struct facebook::react::bridging::Converter<std::optional<T>> : public facebook::react::bridging::ConverterBase<T>, public facebook::react::bridging::ConverterBase<facebook::jsi::Value> {
+struct facebook::react::bridging::Converter<std::optional<T>> : public facebook::react::bridging::ConverterBase<facebook::jsi::Value> {
   public Converter(facebook::jsi::Runtime& rt, std::optional<T> value);
   public operator std::optional<T>();
 }
 
 template <typename T>
-struct facebook::react::bridging::is_optional<std::optional<T>> : public std::false_type, public std::true_type {
+struct facebook::react::bridging::is_optional<std::optional<T>> : public std::true_type {
 }
 
-struct facebook::react::bridging::Converter<facebook::jsi::Object> : public facebook::react::bridging::ConverterBase<facebook::jsi::Object>, public facebook::react::bridging::ConverterBase<facebook::jsi::Object> {
+struct facebook::react::bridging::Converter<facebook::jsi::Object> : public facebook::react::bridging::ConverterBase<facebook::jsi::Object> {
   public operator jsi::Array();
   public operator jsi::Function();
 }
 
-struct facebook::react::bridging::Converter<facebook::jsi::Value> : public facebook::react::bridging::ConverterBase<facebook::jsi::Value>, public facebook::react::bridging::ConverterBase<facebook::jsi::Value> {
+struct facebook::react::bridging::Converter<facebook::jsi::Value> : public facebook::react::bridging::ConverterBase<facebook::jsi::Value> {
   public operator jsi::Array();
   public operator jsi::Function();
   public operator jsi::Object();

scripts/cxx-api/api-snapshots/ReactAppleDebugCxx.api

@@ -13330,7 +13330,7 @@ struct facebook::react::detail::merge_data_types<std::variant<AllowedTypesT...>>
 }
 
 template <CSSDataType... Ts>
-struct facebook::react::detail::is_variant_of_data_types<std::variant<Ts...>> : public std::false_type, public std::true_type {
+struct facebook::react::detail::is_variant_of_data_types<std::variant<Ts...>> : public std::true_type {
 }
 
 template <CSSDataType... AlllowedTypes1T, CSSDataType... AlllowedTypes2T, CSSMaybeCompoundDataType... RestT>
@@ -14862,21 +14862,21 @@ struct facebook::react::bridging::is_optional : public std::false_type {
 }
 
 template <typename T>
-struct facebook::react::bridging::Converter<std::optional<T>> : public facebook::react::bridging::ConverterBase<T>, public facebook::react::bridging::ConverterBase<facebook::jsi::Value> {
+struct facebook::react::bridging::Converter<std::optional<T>> : public facebook::react::bridging::ConverterBase<facebook::jsi::Value> {
   public Converter(facebook::jsi::Runtime& rt, std::optional<T> value);
   public operator std::optional<T>();
 }
 
 template <typename T>
-struct facebook::react::bridging::is_optional<std::optional<T>> : public std::false_type, public std::true_type {
+struct facebook::react::bridging::is_optional<std::optional<T>> : public std::true_type {
 }
 
-struct facebook::react::bridging::Converter<facebook::jsi::Object> : public facebook::react::bridging::ConverterBase<facebook::jsi::Object>, public facebook::react::bridging::ConverterBase<facebook::jsi::Object> {
+struct facebook::react::bridging::Converter<facebook::jsi::Object> : public facebook::react::bridging::ConverterBase<facebook::jsi::Object> {
   public operator jsi::Array();
   public operator jsi::Function();
 }
 
-struct facebook::react::bridging::Converter<facebook::jsi::Value> : public facebook::react::bridging::ConverterBase<facebook::jsi::Value>, public facebook::react::bridging::ConverterBase<facebook::jsi::Value> {
+struct facebook::react::bridging::Converter<facebook::jsi::Value> : public facebook::react::bridging::ConverterBase<facebook::jsi::Value> {
   public operator jsi::Array();
   public operator jsi::Function();
   public operator jsi::Object();

scripts/cxx-api/api-snapshots/ReactAppleReleaseCxx.api

@@ -13157,7 +13157,7 @@ struct facebook::react::detail::merge_data_types<std::variant<AllowedTypesT...>>
 }
 
 template <CSSDataType... Ts>
-struct facebook::react::detail::is_variant_of_data_types<std::variant<Ts...>> : public std::false_type, public std::true_type {
+struct facebook::react::detail::is_variant_of_data_types<std::variant<Ts...>> : public std::true_type {
 }
 
 template <CSSDataType... AlllowedTypes1T, CSSDataType... AlllowedTypes2T, CSSMaybeCompoundDataType... RestT>
@@ -14689,21 +14689,21 @@ struct facebook::react::bridging::is_optional : public std::false_type {
 }
 
 template <typename T>
-struct facebook::react::bridging::Converter<std::optional<T>> : public facebook::react::bridging::ConverterBase<T>, public facebook::react::bridging::ConverterBase<facebook::jsi::Value> {
+struct facebook::react::bridging::Converter<std::optional<T>> : public facebook::react::bridging::ConverterBase<facebook::jsi::Value> {
   public Converter(facebook::jsi::Runtime& rt, std::optional<T> value);
   public operator std::optional<T>();
 }
 
 template <typename T>
-struct facebook::react::bridging::is_optional<std::optional<T>> : public std::false_type, public std::true_type {
+struct facebook::react::bridging::is_optional<std::optional<T>> : public std::true_type {
 }
 
-struct facebook::react::bridging::Converter<facebook::jsi::Object> : public facebook::react::bridging::ConverterBase<facebook::jsi::Object>, public facebook::react::bridging::ConverterBase<facebook::jsi::Object> {
+struct facebook::react::bridging::Converter<facebook::jsi::Object> : public facebook::react::bridging::ConverterBase<facebook::jsi::Object> {
   public operator jsi::Array();
   public operator jsi::Function();
 }
 
-struct facebook::react::bridging::Converter<facebook::jsi::Value> : public facebook::react::bridging::ConverterBase<facebook::jsi::Value>, public facebook::react::bridging::ConverterBase<facebook::jsi::Value> {
+struct facebook::react::bridging::Converter<facebook::jsi::Value> : public facebook::react::bridging::ConverterBase<facebook::jsi::Value> {
   public operator jsi::Array();
   public operator jsi::Function();
   public operator jsi::Object();

scripts/cxx-api/api-snapshots/ReactCommonDebugCxx.api

@@ -7630,7 +7630,7 @@ struct facebook::react::detail::merge_data_types<std::variant<AllowedTypesT...>>
 }
 
 template <CSSDataType... Ts>
-struct facebook::react::detail::is_variant_of_data_types<std::variant<Ts...>> : public std::false_type, public std::true_type {
+struct facebook::react::detail::is_variant_of_data_types<std::variant<Ts...>> : public std::true_type {
 }
 
 template <CSSDataType... AlllowedTypes1T, CSSDataType... AlllowedTypes2T, CSSMaybeCompoundDataType... RestT>
@@ -9155,21 +9155,21 @@ struct facebook::react::bridging::is_optional : public std::false_type {
 }
 
 template <typename T>
-struct facebook::react::bridging::Converter<std::optional<T>> : public facebook::react::bridging::ConverterBase<T>, public facebook::react::bridging::ConverterBase<facebook::jsi::Value> {
+struct facebook::react::bridging::Converter<std::optional<T>> : public facebook::react::bridging::ConverterBase<facebook::jsi::Value> {
   public Converter(facebook::jsi::Runtime& rt, std::optional<T> value);
   public operator std::optional<T>();
 }
 
 template <typename T>
-struct facebook::react::bridging::is_optional<std::optional<T>> : public std::false_type, public std::true_type {
+struct facebook::react::bridging::is_optional<std::optional<T>> : public std::true_type {
 }
 
-struct facebook::react::bridging::Converter<facebook::jsi::Object> : public facebook::react::bridging::ConverterBase<facebook::jsi::Object>, public facebook::react::bridging::ConverterBase<facebook::jsi::Object> {
+struct facebook::react::bridging::Converter<facebook::jsi::Object> : public facebook::react::bridging::ConverterBase<facebook::jsi::Object> {
   public operator jsi::Array();
   public operator jsi::Function();
 }
 
-struct facebook::react::bridging::Converter<facebook::jsi::Value> : public facebook::react::bridging::ConverterBase<facebook::jsi::Value>, public facebook::react::bridging::ConverterBase<facebook::jsi::Value> {
+struct facebook::react::bridging::Converter<facebook::jsi::Value> : public facebook::react::bridging::ConverterBase<facebook::jsi::Value> {
   public operator jsi::Array();
   public operator jsi::Function();
   public operator jsi::Object();

scripts/cxx-api/api-snapshots/ReactCommonReleaseCxx.api

@@ -7621,7 +7621,7 @@ struct facebook::react::detail::merge_data_types<std::variant<AllowedTypesT...>>
 }
 
 template <CSSDataType... Ts>
-struct facebook::react::detail::is_variant_of_data_types<std::variant<Ts...>> : public std::false_type, public std::true_type {
+struct facebook::react::detail::is_variant_of_data_types<std::variant<Ts...>> : public std::true_type {
 }
 
 template <CSSDataType... AlllowedTypes1T, CSSDataType... AlllowedTypes2T, CSSMaybeCompoundDataType... RestT>
@@ -9146,21 +9146,21 @@ struct facebook::react::bridging::is_optional : public std::false_type {
 }
 
 template <typename T>
-struct facebook::react::bridging::Converter<std::optional<T>> : public facebook::react::bridging::ConverterBase<T>, public facebook::react::bridging::ConverterBase<facebook::jsi::Value> {
+struct facebook::react::bridging::Converter<std::optional<T>> : public facebook::react::bridging::ConverterBase<facebook::jsi::Value> {
   public Converter(facebook::jsi::Runtime& rt, std::optional<T> value);
   public operator std::optional<T>();
 }
 
 template <typename T>
-struct facebook::react::bridging::is_optional<std::optional<T>> : public std::false_type, public std::true_type {
+struct facebook::react::bridging::is_optional<std::optional<T>> : public std::true_type {
 }
 
-struct facebook::react::bridging::Converter<facebook::jsi::Object> : public facebook::react::bridging::ConverterBase<facebook::jsi::Object>, public facebook::react::bridging::ConverterBase<facebook::jsi::Object> {
+struct facebook::react::bridging::Converter<facebook::jsi::Object> : public facebook::react::bridging::ConverterBase<facebook::jsi::Object> {
   public operator jsi::Array();
   public operator jsi::Function();
 }
 
-struct facebook::react::bridging::Converter<facebook::jsi::Value> : public facebook::react::bridging::ConverterBase<facebook::jsi::Value>, public facebook::react::bridging::ConverterBase<facebook::jsi::Value> {
+struct facebook::react::bridging::Converter<facebook::jsi::Value> : public facebook::react::bridging::ConverterBase<facebook::jsi::Value> {
   public operator jsi::Array();
   public operator jsi::Function();
   public operator jsi::Object();

scripts/cxx-api/parser/scope/extendable.py

@@ -25,6 +25,20 @@ def add_base(self, base: Base | list[Base]) -> None:
                 self.base_classes.append(b)
         else:
             self.base_classes.append(base)
+        self._deduplicate_base_classes()
+
+    def _deduplicate_base_classes(self) -> None:
+        """Remove duplicate base classes.
+
+        Doxygen sometimes reports the same base class multiple times (e.g.
+        when template argument substitution produces identical names for
+        a primary template and its specialization).  This keeps only the
+        last occurrence of each name.
+        """
+        seen: dict[str, int] = {}
+        for i, base in enumerate(self.base_classes):
+            seen[base.name] = i
+        self.base_classes = [self.base_classes[i] for i in sorted(seen.values())]
 
     def qualify_base_classes(self, scope) -> None:
         """Qualify base class names and their template arguments."""

scripts/cxx-api/parser/scope/struct_like_scope_kind.py

@@ -42,8 +42,48 @@ def add_template(self, template: Template | [Template]) -> None:
             self.template_list.add(template)
 
     def close(self, scope: Scope) -> None:
+        self._remove_merged_primary_bases(scope)
         self.qualify_base_classes(scope)
 
+    def _remove_merged_primary_bases(self, scope: Scope) -> None:
+        """Remove base classes that Doxygen incorrectly merged from the
+        primary template into a partial specialization.
+
+        In C++ a partial specialization's inheritance list completely
+        replaces the primary template's, but Doxygen merges both lists
+        into the specialization's ``basecompoundref`` elements.
+
+        This method performs count-based subtraction: for each base in
+        the primary template, one matching occurrence (by name) is removed
+        from this specialization's base list.  Count-based subtraction
+        correctly preserves bases that the specialization explicitly
+        re-inherits from the same class as the primary template.
+        """
+        if self.specialization_args is None:
+            return
+        if scope.parent_scope is None:
+            return
+
+        for sibling in scope.parent_scope.inner_scopes.values():
+            if (
+                sibling is not scope
+                and sibling.name == scope.name
+                and isinstance(sibling.kind, StructLikeScopeKind)
+                and sibling.kind.specialization_args is None
+            ):
+                primary_base_counts: dict[str, int] = {}
+                for b in sibling.kind.base_classes:
+                    primary_base_counts[b.name] = primary_base_counts.get(b.name, 0) + 1
+
+                result = []
+                for b in self.base_classes:
+                    if primary_base_counts.get(b.name, 0) > 0:
+                        primary_base_counts[b.name] -= 1
+                    else:
+                        result.append(b)
+                self.base_classes = result
+                break
+
     def to_string(self, scope: Scope) -> str:
         result = ""
 

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

@@ -0,0 +1,19 @@
+struct test::BaseA {
+}
+
+struct test::Derived : public test::BaseA {
+}
+
+struct test::false_type {
+}
+
+struct test::true_type {
+}
+
+template <typename T>
+struct test::is_special<T *> : public test::true_type {
+}
+
+template <typename>
+struct test::is_special : public test::false_type {
+}

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

@@ -0,0 +1,32 @@
+/*
+ * 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 false_type {};
+struct true_type {};
+
+// Primary template inherits from false_type.
+// Partial specialization inherits from true_type.
+// Doxygen may incorrectly merge both base class lists into the
+// specialization, producing : false_type, true_type.  The parser
+// should subtract the primary template's bases and keep only true_type.
+
+template <typename>
+struct is_special : public false_type {};
+
+template <typename T>
+struct is_special<T *> : public true_type {};
+
+// Duplicate base class via Doxygen merging template-substituted bases.
+struct BaseA {};
+
+struct Derived : public BaseA, public BaseA {};
+
+} // namespace test