Fix Doxygen merging base classes from primary templates into specializations (#56239)

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

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]

Reviewed By: cipolleschi

Differential Revision: D98291360

fbshipit-source-id: 82b34969b13c7df8babf2c5efc222b29979d6361
This commit is contained in:
Dawid Małecki authored and meta-codesync[bot] committed 2026-03-31 08:32:57 -07:00
1 parent 1d6e68bfdf
commit d920d109cf
10 files changed
+123 -18

No files matched your search

@@ -10876,7 +10876,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>
@@ -12473,13 +12473,13 @@ 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> {
@@ -10703,7 +10703,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>
@@ -12300,13 +12300,13 @@ 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> {
@@ -13329,7 +13329,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>
@@ -14861,13 +14861,13 @@ 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> {
@@ -13156,7 +13156,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>
@@ -14688,13 +14688,13 @@ 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> {
@@ -7629,7 +7629,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>
@@ -9154,13 +9154,13 @@ 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> {
@@ -7620,7 +7620,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>
@@ -9145,13 +9145,13 @@ 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> {
@@ -25,6 +25,20 @@ class Extendable:
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."""
@@ -42,8 +42,48 @@ class StructLikeScopeKind(ScopeKind, Extendable):
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 = ""
@@ -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 {
}
@@ -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