nodeextractor.cpp

Go to the documentation of this file.

// Copyright (C) 2026 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GPL-3.0-only WITH Qt-GPL-exception-1.0
 
#include "nodeextractor.h"
 
#include "aggregate.h"
#include "atom.h"
#include "classnode.h"
#include "codemarker.h"
#include "collectionnode.h"
#include "comparisoncategory.h"
#include "config.h"
#include "doc.h"
#include "enumnode.h"
#include "functionnode.h"
#include "generator.h"
#include "hrefresolver.h"
#include "inclusionfilter.h"
#include "namespacenode.h"
#include "nodedescription.h"
#include "ir/contentbuilder.h"
#include "ir/signaturespan.h"
#include "pagenode.h"
#include "parameters.h"
#include "propertynode.h"
#include "qmlpropertynode.h"
#include "qdocdatabase.h"
#include "qmltypenode.h"
#include "sections.h"
#include "sharedcommentnode.h"
#include "template_declaration.h"
#include "text.h"
#include "tree.h"
#include "typedefnode.h"
#include "utilities.h"
#include "textutils.h"
#include "variablenode.h"
 
#include "location.h"
 
#include <QHash>
#include <QRegularExpression>
#include <QSet>
 
#include <deque>
#include <optional>
 
QT_BEGIN_NAMESPACE
 
using namespace Qt::Literals;
 
static IR::DiagnosticHandler diagnosticHandlerFor(const Node *node)
{
    const Location &loc = node->doc().location();
    return [loc](QtMsgType type, const QString &message) {
        switch (type) {
        case QtWarningMsg:
            loc.warning(message);
            break;
        default:
            loc.warning(message);
            break;
        }
    };
}
 
static QString resolveHref(const HrefResolver *resolver, const Node *target, const Node *relative)
{
    if (!resolver)
        return target->url();
    auto result = resolver->hrefForNode(target, relative);
    if (const auto *href = std::get_if<QString>(&result))
        return *href;
    return {};
}
 
namespace {
 
struct DeprecationData
{
    QString deprecatedSince;
    QString typeNoun;
    QString deprecatedSinceQualified;
};
 
/*!
    \internal
 
    Returns the deprecation sentence data for \a node if the node is
    deprecated or active with a nonempty deprecation version. Otherwise,
    returns \c{std::nullopt}.
 
    The result contains the type noun and the plain deprecation version.
    For a QML node with a logical module name, \c{deprecatedSinceQualified}
    prefixes the nonempty version with the module name. For other nodes,
    it contains the plain version. Deprecated sentences use this qualified
    version; scheduled sentences use the plain \c{deprecatedSince} version.
 
    A deprecated node without a version still returns sentence data with
    a type noun and two empty version strings.
*/
std::optional<DeprecationData> extractDeprecationData(const Node *node)
{
    const auto status = node->status();
    const auto &version = node->deprecatedSince();
    if (status != Status::Deprecated && (status != Status::Active || version.isEmpty()))
        return std::nullopt;
 
    DeprecationData data{version, NodeText::nodeTypeDescription(node), version};
    if (!version.isEmpty() && node->isQmlNode() && !node->logicalModuleName().isEmpty())
        data.deprecatedSinceQualified = node->logicalModuleName() + ' '_L1 + version;
    return data;
}
 
// Locate a documented \concept node by name. Walks the QDocDatabase search
// order so cross-module references resolve through dependency index trees.
// The relative node is reserved for relative-node-aware scoping in a future
// revision; today the lookup is global.
const Node *findConceptNodeForRelative(const Node *relative, const QString &name)
{
    Q_UNUSED(relative);
    QDocDatabase *qdb = QDocDatabase::qdocDB();
    if (!qdb)
        return nullptr;
    return qdb->findConceptNode(name);
}
 
// Tokenize a requires-clause text against a list of documented concept
// names, emitting a Text/Link/Text/... span sequence into \a out. Mirrors
// the Text+ExternalRef+Text span pattern used for external references, but
// uses SpanRole::Link with an HrefResolver-resolved href instead of an
// external cppreference URL. Used by both the template-head requires
// clause site (inside buildTemplateDeclSpans) and the trailing requires
// site (inside buildCppSynopsisSpans).
//
// Concept names are matched longest first, so a fully-qualified
// "ns::Integral" wins against a bare "Integral" when both occur in the
// same requires clause text. Each matched spelling maps back to its
// fully-qualified name for lookup, so source text that spells a concept
// either qualified or unqualified resolves to the same concept page.
//
// When no concept name appears in the text, the whole clause is emitted as
// a single Text span. Concept identifiers are alphanumeric and underscore
// per the C++ grammar, but the alternation is built through
// QRegularExpression::escape() for defense in depth.
void appendRequiresSpansWithLinks(QList<IR::SignatureSpan> &out,
                                  const QString &requiresText,
                                  const QStringList &conceptNames,
                                  const HrefResolver *hrefResolver,
                                  const Node *relative)
{
    auto emitFallback = [&out, &requiresText]() {
        IR::SignatureSpan req;
        req.role = IR::SpanRole::Text;
        req.text = " requires "_L1 + requiresText;
        out.append(req);
    };
 
    if (conceptNames.isEmpty() || requiresText.isEmpty()) {
        emitFallback();
        return;
    }
 
    QStringList sorted = conceptNames;
    std::sort(sorted.begin(), sorted.end(),
              [](const QString &a, const QString &b) { return a.size() > b.size(); });
 
    // Build a single alternation regex matching any concept name (longest
    // first) anchored at word boundaries, so longer names take priority and
    // overlapping matches don't double-emit. Each matched spelling — the
    // fully-qualified name or its unqualified tail — maps back to the
    // fully-qualified name the lookup needs.
    QHash<QString, QString> targetForDisplay;
    QStringList escapedAlternatives;
    escapedAlternatives.reserve(sorted.size() * 2);
    for (const QString &name : sorted) {
        if (!targetForDisplay.contains(name)) {
            targetForDisplay.insert(name, name);
            escapedAlternatives.append(QRegularExpression::escape(name));
        }
        const QString tail = name.section("::"_L1, -1);
        if (tail != name && !targetForDisplay.contains(tail)) {
            targetForDisplay.insert(tail, name);
            escapedAlternatives.append(QRegularExpression::escape(tail));
        }
    }
    const QRegularExpression conceptRegex(
            u"\\b("_s + escapedAlternatives.join(u"|"_s) + u")\\b"_s);
    if (!conceptRegex.isValid()) {
        emitFallback();
        return;
    }
 
    auto it = conceptRegex.globalMatch(requiresText);
    if (!it.hasNext()) {
        emitFallback();
        return;
    }
 
    // At least one concept matches: emit the " requires " lead-in, then
    // alternate plain-text runs with concept spans.
    IR::SignatureSpan lead;
    lead.role = IR::SpanRole::Text;
    lead.text = " requires "_L1;
    out.append(lead);
 
    qsizetype pos = 0;
    while (it.hasNext()) {
        const auto match = it.next();
        if (match.capturedStart() > pos) {
            IR::SignatureSpan textSpan;
            textSpan.role = IR::SpanRole::Text;
            textSpan.text = requiresText.mid(pos, match.capturedStart() - pos);
            out.append(textSpan);
        }
        const QString matched = match.captured(1);
        const QString target = targetForDisplay.value(matched, matched);
        const Node *cn = findConceptNodeForRelative(relative, target);
        const QString href = cn ? resolveHref(hrefResolver, cn, relative) : QString();
 
        IR::SignatureSpan span;
        span.text = matched;
        if (href.isEmpty()) {
            // An undocumented concept, or one whose page can't be located,
            // renders as plain text rather than a dangling link.
            span.role = IR::SpanRole::Text;
        } else {
            span.role = IR::SpanRole::Link;
            span.href = href;
        }
        out.append(span);
        pos = match.capturedEnd();
    }
    if (pos < requiresText.size()) {
        IR::SignatureSpan tail;
        tail.role = IR::SpanRole::Text;
        tail.text = requiresText.mid(pos);
        out.append(tail);
    }
}
 
}  // namespace
 
namespace NodeExtractor {
 
/*!
  \internal
  \typealias NodeExtractor::SemanticOrigins
 
  Page-local, never serialized: for each emitted detail section, one entry
  per emitted member in the same order, pointing at the node on which that
  member's detail documentation was authored. For a regular member the
  origin is the member itself; for a member of a SharedCommentNode group it
  is the SharedCommentNode, because the copied body and see-also text was
  authored in that comment. A member without an anchorId maps to nullptr,
  which the link resolver treats as "resolve in page context".
 
  The list is paired with the extracted detail-section and member order
  rather than keyed by anchorId: emitted anchors are not unique, so two
  members (such as a QML type's regular and attached signal of the same
  name) can share one anchorId. The pairing travels beside the IR values,
  not inside them.
*/
 
/*!
    \internal
    Extract page-level metadata from a PageNode into a value-type struct.
 
    This function reads classification, identity, brief, and body fields
    from the given PageNode and returns them as an IR::PageMetadata value.
    Body content is populated via ContentBuilder, which transforms the
    atom chain into structured content blocks. Format-conditional atoms
    are skipped unconditionally since the template generator builds a
    format-agnostic IR.
 
    For aggregate pages (classes, QML types, namespaces), member listings
    are extracted via the Sections infrastructure and stored as frozen
    SectionIR values.
 
    The caller (TemplateGenerator) invokes this before passing the
    result to IR::Builder, ensuring Builder never includes PageNode
    or other Node subclass headers.
 
    \a origins, when non-null, is populated alongside detail extraction
    with a page-local origin paired with each emitted detail member, in
    section and member order, for the template post-processing that
    resolves links in the authored member context.
*/
IR::PageMetadata extractPageMetadata(const PageNode *pn, const HrefResolver *hrefResolver,
                                     SemanticOrigins *origins)
{
    Q_ASSERT_X(pn, "NodeExtractor::extractPageMetadata",
               "PageNode pointer must be non-null");
    IR::PageMetadata pm;
 
    pm.nodeType = pn->nodeType();
    pm.genus = pn->genus();
    pm.status = pn->status();
    pm.access = pn->access();
 
    if (pn->isQmlType()) {
        const auto *qcn = static_cast<const QmlTypeNode *>(pn);
        QString suffix = qcn->isQmlBasicType() ? " QML Value Type"_L1 : " QML Type"_L1;
        pm.title = pn->name() + suffix;
        pm.fullTitle = pm.title;
    } else if (pn->isClassNode() || pn->isNamespace() || pn->isHeader()) {
        // plainFullName() produces qualified names for nested aggregates
        // (e.g. "Outer::Inner"), matching the legacy generator behavior.
        // For top-level types and headers the result is the same as name().
        const auto *aggregate = static_cast<const Aggregate *>(pn);
        pm.fullTitle = aggregate->plainFullName();
        pm.title = pm.fullTitle;
    } else {
        pm.title = pn->title();
        pm.fullTitle = pn->fullTitle();
    }
 
    pm.url = hrefResolver->fileName(pn);
    const QString baseUrl = Config::instance().get(CONFIG_URL).asString();
    if (!baseUrl.isEmpty() && !pm.url.isEmpty() && !pm.url.contains("://"_L1)) {
        pm.url = baseUrl
                + (baseUrl.endsWith(u'/') ? QString{} : QStringLiteral("/"))
                + pm.url;
    }
    pm.since = pn->since();
    pm.deprecatedSince = pn->deprecatedSince();
    if (const auto deprecation = extractDeprecationData(pn)) {
        pm.typeNoun = deprecation->typeNoun;
        pm.deprecatedSinceQualified = deprecation->deprecatedSinceQualified;
    }
    pm.brief = pn->doc().briefText().toString();
 
    const Text &bodyText = pn->doc().body();
    if (const Atom *firstAtom = bodyText.firstAtom()) {
        // Offset section heading levels to account for page structure.
        // QDoc's \section1 maps to level 1, but pages already use <h1>
        // for the title. The legacy generators apply a node-type-dependent
        // offset; we replicate the same mapping here.
        const int headingOffset = [&] {
            switch (pn->nodeType()) {
            case NodeType::Namespace:
            case NodeType::Class:
            case NodeType::Struct:
            case NodeType::Union:
            case NodeType::Module:
                return 2;
            case NodeType::QmlModule:
            case NodeType::QmlValueType:
            case NodeType::QmlType:
            case NodeType::Page:
            case NodeType::Group:
                return 1;
            default:
                return 3;
            }
        }();
        IR::ContentBuilder contentBuilder(IR::BriefHandling::Skip, headingOffset,
                                          diagnosticHandlerFor(pn));
        pm.body = contentBuilder.build(firstAtom);
    }
 
    if (pn->isAggregate()) {
        const auto *aggregate = static_cast<const Aggregate *>(pn);
        pm.summarySections = extractSummarySections(aggregate, hrefResolver);
        pm.detailSections = extractDetailSections(aggregate, hrefResolver, origins);
    }
 
    if (pn->isQmlType()) {
        const auto *qcn = static_cast<const QmlTypeNode *>(pn);
        pm.qmlTypeData = extractQmlTypeData(qcn, hrefResolver);
    }
 
    if (pn->isCollectionNode()) {
        const auto *cn = static_cast<const CollectionNode *>(pn);
        pm.collectionData = extractCollectionData(cn, hrefResolver);
    }
 
    if (pn->isClassNode() || pn->isNamespace() || pn->isHeader()) {
        const auto *aggregate = static_cast<const Aggregate *>(pn);
        pm.cppReferenceData = extractCppReferenceData(aggregate, hrefResolver);
    }
 
    pm.navigationData = extractNavigationData(pn, hrefResolver);
 
    return pm;
}
 
/*!
    \internal
    Extract QML type metadata from a QmlTypeNode.
 
    Populates import statement, inheritance chain, inherited-by list,
    native C++ type link, and singleton/value-type flags. InclusionFilter
    is applied to match the legacy generator's visibility filtering.
 
    hasObsoleteMembers reports whether any section holds deprecated
    members, the same check the legacy QML generator applies before
    generating its obsolete sub-page. The check walks the section
    distribution rather than only direct children so members inherited
    from an abstract base type count as well.
*/
IR::QmlTypeData extractQmlTypeData(const QmlTypeNode *qcn, const HrefResolver *hrefResolver)
{
    IR::QmlTypeData data;
    const InclusionPolicy policy = Config::instance().createInclusionPolicy();
 
    if (!qcn->logicalModuleName().isEmpty()) {
        bool includeImport = true;
        const CollectionNode *collection = qcn->logicalModule();
        if (collection) {
            const NodeContext context = collection->createContext();
            includeImport = InclusionFilter::isIncluded(policy, context);
        }
        if (includeImport) {
            QStringList parts = QStringList()
                << "import"_L1 << qcn->logicalModuleName() << qcn->logicalModuleVersion();
            data.importStatement = parts.join(' '_L1).trimmed();
        }
    }
 
    data.isSingleton = qcn->isSingleton();
    data.isValueType = qcn->isQmlBasicType();
 
    QmlTypeNode *base = qcn->qmlBaseNode();
    while (base) {
        const NodeContext context = base->createContext();
        if (InclusionFilter::isIncluded(policy, context))
            break;
        base = base->qmlBaseNode();
    }
 
    NodeList subs;
    QmlTypeNode::subclasses(qcn, subs, true);
 
    if (base) {
        IR::QmlTypeData::InheritsInfo inheritsInfo;
        inheritsInfo.name = base->name();
        inheritsInfo.href = resolveHref(hrefResolver, base, qcn);
        const CollectionNode *baseModule = base->logicalModule();
        if (baseModule) {
            const NodeContext moduleContext = baseModule->createContext();
            if (InclusionFilter::isIncluded(policy, moduleContext))
                inheritsInfo.moduleName = base->logicalModuleName();
        }
        data.inherits = inheritsInfo;
    }
 
    if (!subs.isEmpty()) {
        QList<IR::QmlTypeData::InheritedByEntry> filteredSubs;
        for (const auto *sub : std::as_const(subs)) {
            const NodeContext context = sub->createContext();
            if (InclusionFilter::isIncluded(policy, context))
                filteredSubs.append({sub->name(), resolveHref(hrefResolver, sub, qcn)});
        }
        std::sort(filteredSubs.begin(), filteredSubs.end(),
                  [](const IR::QmlTypeData::InheritedByEntry &a,
                     const IR::QmlTypeData::InheritedByEntry &b) {
                      return a.name < b.name;
                  });
        data.inheritedBy = filteredSubs;
    }
 
    ClassNode *cn = qcn->classNode();
    if (cn && cn->isQmlNativeType()) {
        const NodeContext context = cn->createContext();
        if (InclusionFilter::isIncluded(policy, context))
            data.nativeType = IR::QmlTypeData::NativeTypeInfo{cn->name(), resolveHref(hrefResolver, cn, qcn)};
    }
 
    SectionPtrVector obsoleteSummary;
    SectionPtrVector obsoleteDetail;
    Sections sections(qcn);
    data.hasObsoleteMembers = sections.hasObsoleteMembers(&obsoleteSummary, &obsoleteDetail);
 
    return data;
}
 
/*!
    \internal
    Extract collection metadata from a CollectionNode.
 
    Populates module identity, CMake/qmake build variables, technology
    preview state, and pre-sorted member listings. For C++ modules,
    members are categorized into separate namespace and class lists.
    For groups and QML modules, a single flat member list is produced.
 
    All member lists are filtered through InclusionFilter (excluding
    internal entries) and exclude deprecated nodes, then sorted
    alphabetically by name (case-insensitive).
*/
IR::CollectionData extractCollectionData(const CollectionNode *cn, const HrefResolver *hrefResolver)
{
    IR::CollectionData data;
 
    data.logicalModuleName = cn->logicalModuleName();
    data.logicalModuleVersion = cn->logicalModuleVersion();
    data.qtVariable = cn->qtVariable();
 
    // CMake metadata synthesis. Documenters can declare CMake info
    // through several command shapes (\cmakepackage, \cmakecomponent,
    // \cmaketargetitem and the Qt-specific \qtcmakepackage and
    // \qtcmaketargetitem) that populate different combinations of
    // the package, component and target fields on the CollectionNode.
    // Synthesize the package as Qt<major-version> when only a
    // component is declared, so module pages render coherent
    // find_package snippets for both the generic and Qt-flavored
    // command families. The target_link_libraries line is
    // synthesized only when a component is also available — a bare
    // package name does not imply a target named package::package,
    // so packages without a component leave the target empty and
    // the template suppresses the target_link_libraries clause.
    // When no field is set, leave the data fields empty so the
    // template suppresses the CMake row entirely.
    const QString rawCmakePackage = cn->cmakePackage();
    const QString rawCmakeComponent = cn->cmakeComponent();
    const QString rawCmakeTargetItem = cn->cmakeTargetItem();
    if (!rawCmakePackage.isEmpty() || !rawCmakeComponent.isEmpty()) {
        const QString package = rawCmakePackage.isEmpty()
                ? "Qt"_L1 + QString::number(QT_VERSION_MAJOR)
                : rawCmakePackage;
        data.cmakePackage = package;
        data.cmakeComponent = rawCmakeComponent;
        if (!rawCmakeTargetItem.isEmpty())
            data.cmakeTargetItem = rawCmakeTargetItem;
        else if (!rawCmakeComponent.isEmpty())
            data.cmakeTargetItem = package + "::"_L1 + rawCmakeComponent;
    }
 
    data.state = cn->state();
 
    data.isModule = cn->isModule();
    data.isQmlModule = cn->isQmlModule();
    data.isGroup = cn->isGroup();
    data.isConcept = cn->isConcept();
    data.noAutoList = cn->noAutoList();
 
    if (cn->noAutoList())
        return data;
 
    const InclusionPolicy policy = Config::instance().createInclusionPolicy();
 
    auto makeMemberEntry = [hrefResolver, cn](const Node *node) -> IR::CollectionData::MemberEntry {
        return { node->name(), resolveHref(hrefResolver, node, cn), node->doc().briefText().toString() };
    };
 
    auto sortEntries = [](QList<IR::CollectionData::MemberEntry> &entries) {
        std::sort(entries.begin(), entries.end(),
                  [](const IR::CollectionData::MemberEntry &a,
                     const IR::CollectionData::MemberEntry &b) {
                      return a.name.compare(b.name, Qt::CaseInsensitive) < 0;
                  });
    };
 
    if (cn->isModule()) {
        const NodeMap nsMap = cn->getMembers(NodeType::Namespace);
        for (auto *node : nsMap.values()) {
            const NodeContext context = node->createContext();
            if (InclusionFilter::isIncluded(policy, context) && !node->isDeprecated())
                data.namespaces.append(makeMemberEntry(node));
        }
        sortEntries(data.namespaces);
 
        const NodeMap classMap = cn->getMembers([](const Node *n) { return n->isClassNode(); });
        for (auto *node : classMap.values()) {
            const NodeContext context = node->createContext();
            if (InclusionFilter::isIncluded(policy, context) && !node->isDeprecated())
                data.classes.append(makeMemberEntry(node));
        }
        sortEntries(data.classes);
    } else {
        for (const auto *node : cn->members()) {
            if (!node->isInAPI())
                continue;
            const NodeContext context = node->createContext();
            if (InclusionFilter::isIncluded(policy, context) && !node->isDeprecated())
                data.members.append(makeMemberEntry(node));
        }
        sortEntries(data.members);
    }
 
    return data;
}
 
static QList<IR::SignatureSpan> buildTemplateDeclSpans(const RelaxedTemplateDeclaration *templateDecl,
                                                       const HrefResolver *hrefResolver,
                                                       const Node *relative);
 
/*!
    \internal
    Extract C++ reference page metadata from a class, namespace, or header.
 
    Reads requisite table fields (header include, build-system snippets,
    status), inheritance hierarchies, template declarations, comparison
    operators, thread-safeness, and group associations. The result is a
    value-type struct that captures everything the template generator needs
    to render the requisites table and secondary sections without touching
    the Node tree at render time.
 
    All three aggregate page types (ClassNode, NamespaceNode, HeaderNode)
    are handled, with ClassNode-specific sections gated on isClassNode().
*/
IR::CppReferenceData extractCppReferenceData(const Aggregate *aggregate, const HrefResolver *hrefResolver)
{
    IR::CppReferenceData data;
    QDocDatabase *qdb = QDocDatabase::qdocDB();
 
    data.isNamespace = aggregate->isNamespace();
    data.isHeader = aggregate->isHeader();
    data.isInnerClass = aggregate->parent() && aggregate->parent()->isClassNode();
    data.typeWord = aggregate->typeWord(false);
    data.hasObsoleteMembers = aggregate->hasObsoleteMembers();
 
    auto ancestors = aggregate->plainFullName().split("::"_L1);
    ancestors.pop_back();
    data.ancestorNames = ancestors;
 
    if (aggregate->includeFile())
        data.headerInclude = *aggregate->includeFile();
 
    if (!aggregate->physicalModuleName().isEmpty()) {
        const CollectionNode *cn =
            qdb->getCollectionNode(aggregate->physicalModuleName(), NodeType::Module);
        if (cn && (!cn->cmakeComponent().isEmpty() || !cn->cmakePackage().isEmpty())) {
            const QString package = cn->cmakePackage().isEmpty()
                ? "Qt"_L1 + QString::number(QT_VERSION_MAJOR)
                : cn->cmakePackage();
            QString findPkg;
            if (cn->cmakeComponent().isEmpty())
                findPkg = "find_package("_L1 + package + " REQUIRED)"_L1;
            else
                findPkg = "find_package("_L1 + package + " REQUIRED COMPONENTS "_L1
                    + cn->cmakeComponent() + ")"_L1;
 
            QString target;
            if (!cn->cmakeTargetItem().isEmpty()) {
                target = cn->cmakeTargetItem();
            } else if (cn->cmakeComponent().isEmpty()) {
                target = package + "::"_L1 + package;
            } else {
                target = package + "::"_L1 + cn->cmakeComponent();
            }
 
            data.cmakeFindPackage = findPkg;
            data.cmakeTargetLinkLibraries =
                "target_link_libraries(mytarget PRIVATE "_L1 + target + ")"_L1;
        }
        if (cn && !cn->qtVariable().isEmpty())
            data.qmakeVariable = "QT += "_L1 + cn->qtVariable();
    }
 
    auto statusOpt = formatStatus(aggregate, qdb);
    if (statusOpt) {
        data.statusText = *statusOpt;
        if (aggregate->status() == Status::Deprecated)
            data.statusCssClass = "deprecated"_L1;
        else if (!aggregate->deprecatedSince().isEmpty())
            data.statusCssClass = "pending-deprecation"_L1;
        else if (aggregate->status() == Status::Preliminary)
            data.statusCssClass = "preliminary"_L1;
        else
            data.statusCssClass = "status"_L1;
    }
 
    if (aggregate->isClassNode()) {
        auto *classNode = const_cast<ClassNode *>(static_cast<const ClassNode *>(aggregate));
 
        if (classNode->isQmlNativeType()) {
            const InclusionPolicy policy = Config::instance().createInclusionPolicy();
            const NodeContext context = classNode->createContext();
            if (InclusionFilter::isIncluded(policy, context)) {
                QList<QmlTypeNode *> nativeTypes{classNode->qmlNativeTypes().cbegin(),
                                                  classNode->qmlNativeTypes().cend()};
                if (!nativeTypes.isEmpty()) {
                    std::sort(nativeTypes.begin(), nativeTypes.end(), Node::nodeNameLessThan);
                    data.qmlNativeType = IR::CppReferenceData::QmlNativeTypeLink{
                        nativeTypes.first()->name(),
                        resolveHref(hrefResolver, nativeTypes.first(), aggregate)
                    };
                }
            }
        }
 
        const auto *metaTags = classNode->doc().metaTagMap();
        if (metaTags && metaTags->contains(u"qdoc-suppress-inheritance"_s))
            data.suppressInheritance = true;
 
        if (!data.suppressInheritance) {
            const auto &baseClasses = classNode->baseClasses();
            for (const auto &bc : baseClasses) {
                if (bc.m_node) {
                    data.baseClasses.append({
                        bc.m_node->plainFullName(),
                        resolveHref(hrefResolver, bc.m_node, aggregate),
                        bc.m_access
                    });
                }
            }
 
            const auto &derivedClasses = classNode->derivedClasses();
            for (const auto &dc : derivedClasses) {
                if (dc.m_node) {
                    data.derivedClasses.append({
                        dc.m_node->plainFullName(),
                        resolveHref(hrefResolver, dc.m_node, aggregate)
                    });
                }
            }
            std::sort(data.derivedClasses.begin(), data.derivedClasses.end(),
                      [](const IR::CppReferenceData::DerivedClassEntry &a,
                         const IR::CppReferenceData::DerivedClassEntry &b) {
                          return a.name.compare(b.name, Qt::CaseInsensitive) < 0;
                      });
        }
    }
 
    if (aggregate->templateDecl()) {
        const auto &templateDecl = *aggregate->templateDecl();
        data.templateDeclSpans = buildTemplateDeclSpans(&templateDecl, hrefResolver, aggregate);
        data.referencedConcepts.reserve(int(templateDecl.referenced_concepts.size()));
        for (const auto &s : templateDecl.referenced_concepts)
            data.referencedConcepts.append(QString::fromStdString(s));
    }
 
    const auto selfCategory = aggregate->comparisonCategory();
    if (selfCategory != ComparisonCategory::None)
        data.selfComparisonCategory = QString::fromStdString(comparisonCategoryAsString(selfCategory));
 
    const auto *comparesMap = aggregate->doc().comparesWithMap();
    if (comparesMap && !comparesMap->isEmpty()) {
        for (auto [key, description] : comparesMap->asKeyValueRange()) {
            IR::CppReferenceData::ComparisonEntry entry;
            entry.category = QString::fromStdString(comparisonCategoryAsString(key));
 
            const QStringList types{description.firstAtom()->string().split(';'_L1)};
            entry.comparableTypes = types;
 
            if (description.firstAtom()->next() != description.lastAtom()) {
                Text descText = Text::subText(description.firstAtom()->next(),
                                              description.lastAtom());
                entry.description = descText.toString();
            }
            data.comparisonEntries.append(entry);
        }
    }
 
    Node::ThreadSafeness ts = aggregate->threadSafeness();
    if (ts != Node::UnspecifiedSafeness) {
        IR::CppReferenceData::ThreadSafetyInfo tsInfo;
        switch (ts) {
        case Node::NonReentrant:
            tsInfo.level = "non-reentrant"_L1;
            break;
        case Node::Reentrant:
            tsInfo.level = "reentrant"_L1;
            break;
        case Node::ThreadSafe:
            tsInfo.level = "thread-safe"_L1;
            break;
        default:
            break;
        }
 
        NodeList reentrant, threadsafe, nonreentrant;
        bool hasExceptions = false;
        for (const auto *child : aggregate->childNodes()) {
            if (!child->isDeprecated()) {
                switch (child->threadSafeness()) {
                case Node::Reentrant:
                    reentrant.append(const_cast<Node *>(child));
                    if (ts == Node::ThreadSafe) hasExceptions = true;
                    break;
                case Node::ThreadSafe:
                    threadsafe.append(const_cast<Node *>(child));
                    if (ts == Node::Reentrant) hasExceptions = true;
                    break;
                case Node::NonReentrant:
                    nonreentrant.append(const_cast<Node *>(child));
                    hasExceptions = true;
                    break;
                default:
                    break;
                }
            }
        }
        if (hasExceptions) {
            for (const auto *node : std::as_const(reentrant)) {
                tsInfo.reentrantExceptions.append({
                    node->plainFullName(),
                    resolveHref(hrefResolver, node, aggregate)
                });
            }
            for (const auto *node : std::as_const(threadsafe)) {
                tsInfo.threadSafeExceptions.append({
                    node->plainFullName(),
                    resolveHref(hrefResolver, node, aggregate)
                });
            }
            for (const auto *node : std::as_const(nonreentrant)) {
                tsInfo.nonReentrantExceptions.append({
                    node->plainFullName(),
                    resolveHref(hrefResolver, node, aggregate)
                });
            }
        }
        data.threadSafety = std::move(tsInfo);
    }
 
    const QStringList &groupNames = aggregate->groupNames();
    if (!groupNames.isEmpty()) {
        const auto &groupMap = qdb->groups();
        for (const auto &groupName : groupNames) {
            auto it = groupMap.find(groupName);
            if (it == groupMap.end() || !*it)
                continue;
            CollectionNode *group = *it;
            // TODO: mergeCollections() mutates the node tree during
            // extraction, violating the principle that the new pipeline
            // reads without side effects. Replace with an eager merge
            // pass that runs before generation begins.
            qdb->mergeCollections(group);
            if (group->wasSeen()) {
                data.groups.append({
                    group->fullTitle(),
                    resolveHref(hrefResolver, group, aggregate)
                });
            }
        }
    }
 
    if (aggregate->isNamespace()) {
        const auto *ns = static_cast<const NamespaceNode *>(aggregate);
        if (!ns->hasDoc() && ns->docNode()) {
            data.isPartialNamespace = true;
            data.fullNamespaceHref = resolveHref(hrefResolver, ns->docNode(), aggregate);
            data.fullNamespaceModuleName = ns->docNode()->tree()->camelCaseModuleName();
        }
    }
 
    return data;
}
 
/*!
    \internal
    Build categorized summary sections for an aggregate node.
 
    Delegates to the Sections class for member distribution, then extracts
    results into frozen SectionIR values. The section variant (C++ class,
    QML type, or generic) is chosen based on the aggregate's node type.
*/
QList<IR::SectionIR> extractSummarySections(const Aggregate *aggregate, const HrefResolver *hrefResolver)
{
    Sections sections(aggregate);
 
    const auto &sv = sections.summarySections();
 
    QList<IR::SectionIR> result;
    for (const auto &section : sv) {
        if (section.isEmpty())
            continue;
 
        IR::SectionIR irSection;
        irSection.title = section.title();
        irSection.id = TextUtils::asAsciiPrintable(section.title());
        irSection.singular = section.singular();
        irSection.plural = section.plural();
 
        // SharedCommentNode groups several declarations under one doc comment.
        // Expand them into individual MemberIR entries so each function appears
        // in the member table. This means the IR member count may exceed the
        // Section::members() count.
        for (const auto *member : section.members()) {
            if (member->isSharedCommentNode()) {
                const auto *scn = static_cast<const SharedCommentNode *>(member);
                for (const auto *child : scn->collective()) {
                    IR::MemberIR irMember = extractMemberIR(child, hrefResolver, aggregate);
                    irMember.href = "#"_L1 + hrefResolver->anchorForNode(child);
                    irSection.members.append(irMember);
                }
            } else {
                IR::MemberIR irMember = extractMemberIR(member, hrefResolver, aggregate);
                irMember.href = "#"_L1 + hrefResolver->anchorForNode(member);
                irSection.members.append(irMember);
            }
        }
 
        for (const auto *reimpl : section.reimplementedMembers())
            irSection.reimplementedMembers.append(extractMemberIR(reimpl, hrefResolver, aggregate));
 
        for (const auto &[base, count] : section.inheritedMembers()) {
            IR::InheritedMembersIR inherited;
            inherited.className = base->plainFullName();
            inherited.count = count;
            inherited.href = resolveHref(hrefResolver, base, aggregate);
            irSection.inheritedMembers.append(inherited);
        }
 
        result.append(irSection);
    }
    return result;
}
 
/*!
    \internal
    Build categorized detail sections for an aggregate node.
 
    Iterates Sections::detailsSections() and extracts full member
    documentation including body content, anchor IDs, and metadata.
    SharedCommentNode groups share a single documentation body across
    their children; the body and see-also list are stored once on the
    section's shared detail group, which references its members
    positionally and carries the group's own anchor when it has one
    (named QML property groups do), while each child keeps its own
    anchorId, synopsis, and per-member fields with an empty body and
    see-also list. Because one page fragment may own only one
    destination, a group anchor that collides with a member anchor or
    with an earlier group's anchor on the same page is dropped.
 
    \a origins, when non-null, receives one entry per emitted detail
    member, paired with the member order of each emitted section: the
    node the member's detail documentation was authored on — the member
    itself, or the SharedCommentNode for copied shared text. A member
    without an anchorId maps to nullptr; its content resolves in page
    context. Emitted anchors are not unique (a QML type's regular and
    attached signal of the same name share one), so the pairing is
    positional rather than keyed by anchorId.
*/
QList<IR::SectionIR> extractDetailSections(const Aggregate *aggregate, const HrefResolver *hrefResolver,
                                           SemanticOrigins *origins)
{
    Sections sections(aggregate);
    const auto &sv = sections.detailsSections();
 
    QList<IR::SectionIR> result;
    for (const auto &section : sv) {
        if (section.isEmpty())
            continue;
 
        IR::SectionIR irSection;
        irSection.title = section.title();
        irSection.id = TextUtils::asAsciiPrintable(section.title());
        irSection.singular = section.singular();
        irSection.plural = section.plural();
 
        // Paired with irSection.members: the node each member's detail
        // documentation was authored on (nullptr without an anchor).
        QList<const Node *> sectionOrigins;
 
        for (const auto *member : section.members()) {
            if (member->isSharedCommentNode()) {
                const auto *scn = static_cast<const SharedCommentNode *>(member);
 
                // The body and see-also list are authored on the shared
                // comment, not on any one child, so they are stored once
                // on the group, which the templates render after the
                // group's last member.
                IR::SharedDetailGroup group;
                group.firstIndex = static_cast<int>(irSection.members.size());
                group.count = static_cast<int>(scn->collective().size());
                group.status = scn->status();
                group.isPlural = !scn->isPropertyGroup() && group.count > 1;
                // A named QML property group is itself a link target, so
                // the group carries its own anchor (such as "font-prop")
                // beside its children's. Anonymous shared comments have
                // none; anchorForNode returns an empty string for them.
                group.anchorId = hrefResolver->anchorForNode(scn);
                if (const auto deprecation = extractDeprecationData(scn)) {
                    group.deprecatedSince = deprecation->deprecatedSince;
                    group.deprecatedSinceQualified = deprecation->deprecatedSinceQualified;
                    const Node *described = group.isPlural ? scn->collective().first() : scn;
                    const auto number = group.isPlural ? NodeText::GrammaticalNumber::Plural
                                                       : NodeText::GrammaticalNumber::Singular;
                    group.typeNoun = NodeText::nodeTypeDescription(described, number);
                }
 
                const Text &bodyText = scn->doc().body();
                if (const Atom *firstAtom = bodyText.firstAtom()) {
                    IR::ContentBuilder contentBuilder(IR::BriefHandling::Include, 0,
                                                      diagnosticHandlerFor(scn));
                    group.body = contentBuilder.build(firstAtom);
                }
 
                const QList<Text> &alsoTexts = scn->doc().alsoList();
                for (const Text &alsoText : alsoTexts) {
                    if (const Atom *firstAtom = alsoText.firstAtom()) {
                        IR::ContentBuilder contentBuilder(IR::BriefHandling::Include, 0,
                                                          diagnosticHandlerFor(scn));
                        group.alsoList.append(contentBuilder.build(firstAtom));
                    }
                }
 
                for (const auto *child : scn->collective()) {
                    IR::MemberIR irMember = extractMemberIR(child, hrefResolver, aggregate, MemberExtractionLevel::Detail);
                    // The child shares the group's comment; its body and
                    // see-also list belong to the group, which renders
                    // them once, so the member carries only the group's
                    // index.
                    irMember.body.clear();
                    irMember.alsoList.clear();
                    irMember.sharedGroup = static_cast<int>(irSection.sharedGroups.size());
                    // The shared text was authored in the shared comment,
                    // not on the child; resolve it in that context.
                    sectionOrigins.append(irMember.anchorId.isEmpty() ? nullptr : scn);
                    irSection.members.append(irMember);
                }
                irSection.sharedGroups.append(group);
            } else {
                IR::MemberIR irMember = extractMemberIR(member, hrefResolver, aggregate, MemberExtractionLevel::Detail);
                sectionOrigins.append(irMember.anchorId.isEmpty() ? nullptr : member);
                irSection.members.append(irMember);
            }
        }
 
        if (origins)
            origins->append(std::move(sectionOrigins));
        result.append(irSection);
    }
 
    // A named QML property group emits its own anchor (such as
    // "font-prop") beside its children's, but one page fragment may
    // own only one destination. An ordinary member documented on the
    // page keeps the anchor it already owns, and a group rendered
    // earlier keeps it over a later group with the same anchor, so a
    // colliding group anchor is dropped rather than duplicated.
    QSet<QString> ownedAnchors;
    for (const auto &section : result)
        for (const auto &member : section.members)
            if (!member.anchorId.isEmpty())
                ownedAnchors.insert(member.anchorId);
 
    for (auto &section : result)
        for (auto &group : section.sharedGroups) {
            if (group.anchorId.isEmpty())
                continue;
            if (ownedAnchors.contains(group.anchorId))
                group.anchorId.clear();
            else
                ownedAnchors.insert(group.anchorId);
        }
 
    return result;
}
 
static QString threadSafenessString(Node::ThreadSafeness ts)
{
    switch (ts) {
    case Node::Reentrant:
        return "reentrant"_L1;
    case Node::ThreadSafe:
        return "thread-safe"_L1;
    default:
        return {};
    }
}
 
/*!
    \internal
    Replace the text of each constant in the value tables of \a blocks with
    the value qualified to the enum's declaration scope, so that the
    template generators display the same constant names as the HTML, WebXML,
    and DocBook generators. Value tables of non-enum nodes, such as
    enumeration properties, keep their authored spelling.
*/
static void qualifyEnumValueTerms(const EnumNode *en, QList<IR::ContentBlock> &blocks)
{
    for (auto &block : blocks) {
        if (block.type == IR::BlockType::DefinitionList
                && block.attributes.value(QLatin1String("listType"))
                       == QLatin1String(ATOM_LIST_VALUE)) {
            for (auto &entry : block.children) {
                if (entry.type != IR::BlockType::DefinitionTerm || entry.inlineContent.isEmpty())
                    continue;
                QString raw;
                for (const IR::InlineContent &content : entry.inlineContent)
                    raw += content.plainText();
                const QString qualified = en->qualifiedValueName(raw);
                if (qualified != raw) {
                    IR::InlineContent text;
                    text.type = IR::InlineType::Text;
                    text.text = qualified;
                    entry.inlineContent = { text };
                }
            }
        }
        qualifyEnumValueTerms(en, block.children);
    }
}
 
/*!
    \internal
    Build a MemberIR from a single Node.
 
    Extracts identity, classification, and type-specific data from the node.
    FunctionNode provides signatures, parameters, and overload metadata.
    EnumNode provides scoped/unscoped signature and enum value listings.
    PropertyNode provides a qualified data type signature.
 
    When \a level is MemberExtractionLevel::Detail, also populates
    detail documentation fields: anchorId, synopsis, since,
    threadSafety, comparisonCategory, noexcept metadata, body (via
    ContentBuilder), and alsoList.
*/
IR::MemberIR extractMemberIR(const Node *node, const HrefResolver *hrefResolver, const Node *relative, MemberExtractionLevel level)
{
    const bool includeDetail = (level == MemberExtractionLevel::Detail);
    IR::MemberIR member;
 
    member.name = node->name();
    member.fullName = node->plainFullName();
    member.href = resolveHref(hrefResolver, node, relative);
    member.brief = node->doc().briefText().toString();
 
    member.nodeType = node->nodeType();
    member.access = node->access();
    member.status = node->status();
    if (const auto deprecation = extractDeprecationData(node)) {
        member.deprecatedSince = deprecation->deprecatedSince;
        member.typeNoun = deprecation->typeNoun;
        member.deprecatedSinceQualified = deprecation->deprecatedSinceQualified;
    }
 
    if (node->isFunction()) {
        const auto *fn = static_cast<const FunctionNode *>(node);
        member.signature = fn->signature(
            Node::SignatureReturnType | Node::SignatureDefaultValues);
        member.isStatic = fn->isStatic();
        member.isConst = fn->isConst();
        member.isVirtual = !fn->isNonvirtual();
        member.isSignal = fn->isSignal();
        member.isSlot = fn->isSlot();
        member.overloadNumber = fn->overloadNumber();
        member.isPrimaryOverload = fn->isPrimaryOverload();
 
        const Parameters &params = fn->parameters();
        for (int i = 0; i < params.count(); ++i) {
            IR::ParameterIR param;
            param.type = params.at(i).type();
            param.name = params.at(i).name();
            param.defaultValue = params.at(i).defaultValue();
            member.parameters.append(param);
        }
    } else if (node->isEnumType()) {
        const auto *en = static_cast<const EnumNode *>(node);
        member.signature = en->isScoped()
            ? "enum class %1"_L1.arg(en->name())
            : "enum %1"_L1.arg(en->name());
 
        for (const auto &item : en->items()) {
            IR::EnumValueIR ev;
            ev.name = item.name();
            ev.value = item.value();
            ev.since = item.since();
            member.enumValues.append(ev);
        }
    } else if (node->isQmlProperty()) {
        const auto *qpn = static_cast<const QmlPropertyNode *>(node);
        member.signature = qpn->name() + " : "_L1 + qpn->dataType();
        member.dataType = qpn->dataType();
        member.isAttached = qpn->isAttached();
        member.isDefault = qpn->isDefault();
        member.isReadOnly = qpn->isReadOnly();
        member.isRequired = qpn->isRequired();
    } else if (node->isProperty()) {
        const auto *pn = static_cast<const PropertyNode *>(node);
        member.signature = pn->name() + " : "_L1 + pn->qualifiedDataType();
    } else if (node->isTypedef()) {
        const auto *td = static_cast<const TypedefNode *>(node);
        member.signature = td->associatedEnum()
            ? "flags "_L1 + td->name()
            : td->name();
    } else if (node->nodeType() == NodeType::Variable) {
        const auto *vn = static_cast<const VariableNode *>(node);
        member.signature = vn->leftType() + vn->name() + vn->rightType();
    } else {
        member.signature = node->name();
    }
 
    if (includeDetail) {
        member.anchorId = hrefResolver->anchorForNode(node);
        member.synopsis = member.signature;
        member.since = node->since();
        member.threadSafety = threadSafenessString(node->threadSafeness());
 
        const std::string catStr = comparisonCategoryAsString(node->comparisonCategory());
        if (!catStr.empty())
            member.comparisonCategory = QString::fromStdString(catStr);
 
        if (node->isFunction()) {
            const auto *fn = static_cast<const FunctionNode *>(node);
            const auto &noexcept_ = fn->getNoexcept();
            if (noexcept_) {
                member.isNoexcept = true;
                member.noexceptNote = *noexcept_;
            }
        }
 
        const Text &bodyText = node->doc().body();
        if (const Atom *firstAtom = bodyText.firstAtom()) {
            IR::ContentBuilder contentBuilder(IR::BriefHandling::Include, 0,
                                              diagnosticHandlerFor(node));
            member.body = contentBuilder.build(firstAtom);
            if (node->isEnumType())
                qualifyEnumValueTerms(static_cast<const EnumNode *>(node), member.body);
        }
 
        const QList<Text> &alsoTexts = node->doc().alsoList();
        for (const Text &alsoText : alsoTexts) {
            if (const Atom *firstAtom = alsoText.firstAtom()) {
                IR::ContentBuilder contentBuilder(IR::BriefHandling::Include, 0,
                                                  diagnosticHandlerFor(node));
                QList<IR::ContentBlock> blocks = contentBuilder.build(firstAtom);
                member.alsoList.append(blocks);
            }
        }
    }
 
    Section::Style spanStyle = includeDetail ? Section::Details : Section::Summary;
    member.signatureSpans = buildSignatureSpans(node, hrefResolver, relative, spanStyle);
 
    return member;
}
 
static QList<IR::SignatureSpan> buildTypeSpans(const QString &typeString)
{
    QList<IR::SignatureSpan> spans;
    QString pendingWord;
 
    for (int i = 0; i <= typeString.size(); ++i) {
        QChar ch;
        if (i != typeString.size())
            ch = typeString.at(i);
 
        QChar lower = ch.toLower();
        if ((lower >= 'a'_L1 && lower <= 'z'_L1) || ch.digitValue() >= 0
            || ch == '_'_L1 || ch == ':'_L1) {
            pendingWord += ch;
        } else {
            if (!pendingWord.isEmpty()) {
                bool isProbablyType = (pendingWord != "const"_L1);
                IR::SignatureSpan span;
                span.role = isProbablyType ? IR::SpanRole::Type : IR::SpanRole::Text;
                span.text = pendingWord;
                spans.append(span);
            }
            pendingWord.clear();
 
            if (!ch.isNull()) {
                IR::SignatureSpan span;
                span.role = IR::SpanRole::Text;
                span.text = QString(ch);
                spans.append(span);
            }
        }
    }
    return spans;
}
 
static QList<IR::SignatureSpan> buildExtraSpans(const Node *node, Section::Style style)
{
    QString extraStr = CodeMarker::extraSynopsis(node, style);
    if (extraStr.isEmpty())
        return {};
 
    // extraSynopsis may contain <@extref target="...">text</@extref> tags for
    // cppreference links. Parse those into ExternalRef spans; everything else
    // becomes Extra spans.
    static const QRegularExpression extrefRegex(
        u"<@extref target=\"([^\"]+)\">([^<]+)</@extref>"_s);
 
    QList<IR::SignatureSpan> spans;
    IR::SignatureSpan wrapper;
    wrapper.role = IR::SpanRole::Extra;
 
    qsizetype pos = 0;
    auto it = extrefRegex.globalMatch(extraStr);
    while (it.hasNext()) {
        auto match = it.next();
        if (match.capturedStart() > pos) {
            IR::SignatureSpan textSpan;
            textSpan.role = IR::SpanRole::Text;
            textSpan.text = extraStr.mid(pos, match.capturedStart() - pos);
            wrapper.children.append(textSpan);
        }
        IR::SignatureSpan ref;
        ref.role = IR::SpanRole::ExternalRef;
        ref.text = match.captured(2);
        ref.href = "https://en.cppreference.com/w/cpp/language/"_L1 + match.captured(1);
        wrapper.children.append(ref);
        pos = match.capturedEnd();
    }
    if (pos < extraStr.size()) {
        IR::SignatureSpan textSpan;
        textSpan.role = IR::SpanRole::Text;
        textSpan.text = extraStr.mid(pos);
        wrapper.children.append(textSpan);
    }
 
    if (wrapper.children.isEmpty()) {
        wrapper.text = extraStr;
    }
    spans.append(wrapper);
    return spans;
}
 
static QList<IR::SignatureSpan> buildTemplateDeclSpans(const RelaxedTemplateDeclaration *templateDecl,
                                                       const HrefResolver *hrefResolver,
                                                       const Node *relative)
{
    if (!templateDecl)
        return {};
 
    IR::SignatureSpan declSpan;
    declSpan.role = IR::SpanRole::TemplateDecl;
    declSpan.text = "template"_L1;
 
    IR::SignatureSpan open;
    open.role = IR::SpanRole::Text;
    open.text = " <"_L1;
    declSpan.children.append(open);
 
    bool first = true;
    for (const auto &param : templateDecl->parameters) {
        if (param.sfinae_constraint)
            continue;
        if (!first) {
            IR::SignatureSpan comma;
            comma.role = IR::SpanRole::Text;
            comma.text = ", "_L1;
            declSpan.children.append(comma);
        }
 
        switch (param.kind) {
        case RelaxedTemplateParameter::Kind::TypeTemplateParameter: {
            if (param.concept_name) {
                const QString fq = QString::fromStdString(*param.concept_name);
                const QString unqualified = fq.section("::"_L1, -1);
                // Resolve by the fully-qualified name the concept is registered
                // under; render the unqualified spelling the author wrote.
                const Node *conceptNode = findConceptNodeForRelative(relative, fq);
                IR::SignatureSpan link;
                link.role = IR::SpanRole::Link;
                link.text = unqualified;
                link.href = resolveHref(hrefResolver, conceptNode, relative);
                declSpan.children.append(link);
            } else {
                IR::SignatureSpan kw;
                kw.role = IR::SpanRole::Text;
                kw.text = "typename"_L1;
                declSpan.children.append(kw);
            }
            break;
        }
        case RelaxedTemplateParameter::Kind::TemplateTemplateParameter: {
            IR::SignatureSpan kw;
            kw.role = IR::SpanRole::Text;
            kw.text = "typename"_L1;
            declSpan.children.append(kw);
            break;
        }
        case RelaxedTemplateParameter::Kind::NonTypeTemplateParameter: {
            if (!param.valued_declaration.type.empty()) {
                auto typeSpans = buildTypeSpans(QString::fromStdString(param.valued_declaration.type));
                declSpan.children.append(typeSpans);
            }
            break;
        }
        }
 
        if (param.is_parameter_pack) {
            IR::SignatureSpan dots;
            dots.role = IR::SpanRole::Text;
            dots.text = "..."_L1;
            declSpan.children.append(dots);
        }
 
        if (!param.valued_declaration.name.empty()) {
            IR::SignatureSpan space;
            space.role = IR::SpanRole::Text;
            space.text = " "_L1;
            declSpan.children.append(space);
 
            IR::SignatureSpan nameSpan;
            nameSpan.role = IR::SpanRole::Parameter;
            nameSpan.text = QString::fromStdString(param.valued_declaration.name);
            declSpan.children.append(nameSpan);
        }
 
        if (!param.valued_declaration.initializer.empty()) {
            IR::SignatureSpan eq;
            eq.role = IR::SpanRole::Text;
            eq.text = " = "_L1;
            declSpan.children.append(eq);
 
            if (param.kind == RelaxedTemplateParameter::Kind::TypeTemplateParameter
                || param.kind == RelaxedTemplateParameter::Kind::TemplateTemplateParameter) {
                auto typeSpans = buildTypeSpans(QString::fromStdString(param.valued_declaration.initializer));
                declSpan.children.append(typeSpans);
            } else {
                IR::SignatureSpan val;
                val.role = IR::SpanRole::Text;
                val.text = QString::fromStdString(param.valued_declaration.initializer);
                declSpan.children.append(val);
            }
        }
 
        first = false;
    }
 
    IR::SignatureSpan close;
    close.role = IR::SpanRole::Text;
    close.text = ">"_L1;
    declSpan.children.append(close);
 
    if (templateDecl->requires_clause && !templateDecl->requires_clause->empty()) {
        const QString reqText = QString::fromStdString(*templateDecl->requires_clause);
        QStringList conceptNames;
        conceptNames.reserve(int(templateDecl->referenced_concepts.size()));
        for (const auto &s : templateDecl->referenced_concepts)
            conceptNames.append(QString::fromStdString(s));
        appendRequiresSpansWithLinks(declSpan.children, reqText, conceptNames,
                                     hrefResolver, relative);
    }
 
    return { declSpan };
}
 
static QList<IR::SignatureSpan> buildCppSynopsisSpans(const Node *node,
                                                       const HrefResolver *hrefResolver,
                                                       const Node *relative,
                                                       Section::Style style)
{
    QList<IR::SignatureSpan> spans;
 
    auto appendText = [&spans](const QString &text) {
        IR::SignatureSpan span;
        span.role = IR::SpanRole::Text;
        span.text = text;
        spans.append(span);
    };
 
    auto appendName = [&spans, node, hrefResolver, relative](const QString &name) {
        IR::SignatureSpan span;
        span.role = IR::SpanRole::Name;
        span.text = name;
        span.href = resolveHref(hrefResolver, node, relative);
        spans.append(span);
    };
 
    auto appendTypeSpans = [&spans](const QString &type, bool trailingSpace) {
        auto typeSpans = buildTypeSpans(type);
        spans.append(typeSpans);
        if (trailingSpace && !type.isEmpty()
            && !type.endsWith('*'_L1) && !type.endsWith('&'_L1)) {
            IR::SignatureSpan space;
            space.role = IR::SpanRole::Text;
            space.text = " "_L1;
            spans.append(space);
        }
    };
 
    // Extra qualifiers go first (prepended in CppCodeMarker)
    if (style != Section::AllMembers) {
        auto extras = buildExtraSpans(node, style);
        if (!extras.isEmpty()) {
            spans.append(extras);
            appendText(" "_L1);
        }
    }
 
    // Name with parent prefix for Details style
    QString nameText = node->name();
    bool linkName = (style != Section::Details);
 
    if (style == Section::Details) {
        if (!node->isRelatedNonmember() && !node->isProxyNode()
            && !node->parent()->name().isEmpty()
            && !node->parent()->isHeader() && !node->isProperty() && !node->isQmlNode()) {
            nameText = node->parent()->name() + "::"_L1 + nameText;
        }
    }
 
    switch (node->nodeType()) {
    case NodeType::Namespace:
    case NodeType::Class:
    case NodeType::Struct:
    case NodeType::Union:
        appendText(Node::nodeTypeString(node->nodeType()) + " "_L1);
        if (linkName) {
            appendName(nameText);
        } else {
            IR::SignatureSpan span;
            span.role = IR::SpanRole::Name;
            span.text = nameText;
            spans.append(span);
        }
        break;
    case NodeType::Function: {
        const auto *func = static_cast<const FunctionNode *>(node);
 
        if (style == Section::Details) {
            if (auto templateDecl = node->templateDecl()) {
                auto tmplSpans = buildTemplateDeclSpans(&*templateDecl, hrefResolver, relative);
                spans.append(tmplSpans);
                appendText(" "_L1);
            }
        }
 
        if (style == Section::Summary || style == Section::Accessors) {
            if (!func->isNonvirtual())
                appendText("virtual "_L1);
        }
 
        if (style != Section::AllMembers && !func->returnType().isEmpty())
            appendTypeSpans(func->returnTypeString(), true);
 
        if (linkName) {
            appendName(nameText);
        } else {
            IR::SignatureSpan span;
            span.role = IR::SpanRole::Name;
            span.text = nameText;
            spans.append(span);
        }
 
        if (!func->isMacroWithoutParams()) {
            appendText("("_L1);
            if (!func->parameters().isEmpty()) {
                const Parameters &parameters = func->parameters();
                for (int i = 0; i < parameters.count(); ++i) {
                    if (i > 0)
                        appendText(", "_L1);
                    const Parameter &param = parameters.at(i);
                    QString pName = param.name();
                    QString type = param.type();
                    QString value = param.defaultValue();
                    qsizetype insertPos = param.nameInsertionPoint();
                    if (insertPos >= 0 && style != Section::AllMembers && !pName.isEmpty()) {
                        appendTypeSpans(type.left(insertPos), false);
                        IR::SignatureSpan paramSpan;
                        paramSpan.role = IR::SpanRole::Parameter;
                        paramSpan.text = pName;
                        spans.append(paramSpan);
                        appendTypeSpans(type.mid(insertPos), false);
                    } else {
                        bool trailingSpace = style != Section::AllMembers && !pName.isEmpty();
                        appendTypeSpans(type, trailingSpace);
                        if (style != Section::AllMembers && !pName.isEmpty()) {
                            IR::SignatureSpan paramSpan;
                            paramSpan.role = IR::SpanRole::Parameter;
                            paramSpan.text = pName;
                            spans.append(paramSpan);
                        }
                    }
                    if (style != Section::AllMembers && !value.isEmpty())
                        appendText(" = "_L1 + value);
                }
            }
            appendText(")"_L1);
        }
 
        if (func->isConst())
            appendText(" const"_L1);
 
        if (style == Section::Summary || style == Section::Accessors) {
            if (func->isFinal())
                appendText(" final"_L1);
            if (func->isOverride())
                appendText(" override"_L1);
            if (func->isPureVirtual())
                appendText(" = 0"_L1);
            if (func->isRef())
                appendText(" &"_L1);
            else if (func->isRefRef())
                appendText(" &&"_L1);
        } else if (style == Section::AllMembers) {
            if (!func->returnType().isEmpty() && func->returnType() != "void"_L1) {
                appendText(" : "_L1);
                appendTypeSpans(func->returnTypeString(), false);
            }
        } else {
            if (func->isRef())
                appendText(" &"_L1);
            else if (func->isRefRef())
                appendText(" &&"_L1);
            if (const auto &req = func->trailingRequiresClause(); req && !req->isEmpty())
                appendRequiresSpansWithLinks(spans, *req, func->referencedConcepts(),
                                             hrefResolver, relative);
        }
        break;
    }
    case NodeType::Enum: {
        const auto *enume = static_cast<const EnumNode *>(node);
        appendText("enum"_L1);
        if (enume->isScoped())
            appendText(" class"_L1);
        if (!enume->isAnonymous()) {
            appendText(" "_L1);
            if (linkName) {
                appendName(nameText);
            } else {
                IR::SignatureSpan span;
                span.role = IR::SpanRole::Name;
                span.text = nameText;
                spans.append(span);
            }
        }
        if (style == Section::Summary) {
            appendText(" { "_L1);
            const int MaxEnumValues = 6;
            QStringList documentedItems = enume->doc().enumItemNames();
            if (documentedItems.isEmpty()) {
                const auto &enumItems = enume->items();
                for (const auto &item : enumItems)
                    documentedItems << item.name();
            }
            const QStringList omitItems = enume->doc().omitEnumItemNames();
            for (const auto &item : omitItems)
                documentedItems.removeAll(item);
 
            if (documentedItems.size() > MaxEnumValues) {
                const QString last = documentedItems.last();
                documentedItems = documentedItems.mid(0, MaxEnumValues - 1);
                documentedItems += "..."_L1;
                documentedItems += last;
            }
            appendText(documentedItems.join(", "_L1));
            if (!documentedItems.isEmpty())
                appendText(" "_L1);
            appendText("}"_L1);
        }
        break;
    }
    case NodeType::TypeAlias: {
        if (style == Section::Details) {
            if (auto templateDecl = node->templateDecl()) {
                auto tmplSpans = buildTemplateDeclSpans(&*templateDecl, hrefResolver, relative);
                spans.append(tmplSpans);
                appendText(" "_L1);
            }
        }
        if (linkName) {
            appendName(nameText);
        } else {
            IR::SignatureSpan span;
            span.role = IR::SpanRole::Name;
            span.text = nameText;
            spans.append(span);
        }
        break;
    }
    case NodeType::Typedef: {
        if (static_cast<const TypedefNode *>(node)->associatedEnum())
            appendText("flags "_L1);
        if (linkName) {
            appendName(nameText);
        } else {
            IR::SignatureSpan span;
            span.role = IR::SpanRole::Name;
            span.text = nameText;
            spans.append(span);
        }
        break;
    }
    case NodeType::Property: {
        const auto *property = static_cast<const PropertyNode *>(node);
        if (linkName) {
            appendName(nameText);
        } else {
            IR::SignatureSpan span;
            span.role = IR::SpanRole::Name;
            span.text = nameText;
            spans.append(span);
        }
        appendText(" : "_L1);
        appendTypeSpans(property->qualifiedDataType(), false);
        break;
    }
    case NodeType::QmlProperty: {
        const auto *property = static_cast<const QmlPropertyNode *>(node);
        if (linkName) {
            appendName(nameText);
        } else {
            IR::SignatureSpan span;
            span.role = IR::SpanRole::Name;
            span.text = nameText;
            spans.append(span);
        }
        appendText(" : "_L1);
        appendTypeSpans(property->dataType(), false);
        break;
    }
    case NodeType::Variable: {
        const auto *variable = static_cast<const VariableNode *>(node);
        if (style == Section::AllMembers) {
            if (linkName) {
                appendName(nameText);
            } else {
                IR::SignatureSpan span;
                span.role = IR::SpanRole::Name;
                span.text = nameText;
                spans.append(span);
            }
            appendText(" : "_L1);
            appendTypeSpans(variable->dataType(), false);
        } else {
            appendTypeSpans(variable->leftType(), true);
            if (linkName) {
                appendName(nameText);
            } else {
                IR::SignatureSpan span;
                span.role = IR::SpanRole::Name;
                span.text = nameText;
                spans.append(span);
            }
            appendText(variable->rightType());
        }
        break;
    }
    default:
        if (linkName) {
            appendName(nameText);
        } else {
            IR::SignatureSpan span;
            span.role = IR::SpanRole::Name;
            span.text = nameText;
            spans.append(span);
        }
        break;
    }
 
    return spans;
}
 
/*!
    \internal
    Build the signature spans for a QML member.
 
    \a relative is the rendered documentation owner: the QML type whose
    page the signature appears on. Inherited members resolve their name
    link against that owner rather than the declaring type, because an
    internal base type generates no page of its own.
*/
static QList<IR::SignatureSpan> buildQmlItemSpans(const Node *node,
                                                   const HrefResolver *hrefResolver,
                                                   const Node *relative)
{
    QList<IR::SignatureSpan> spans;
 
    auto appendText = [&spans](const QString &text) {
        IR::SignatureSpan span;
        span.role = IR::SpanRole::Text;
        span.text = text;
        spans.append(span);
    };
 
    auto appendTypeSpans = [&spans](const QString &type, bool trailingSpace) {
        auto typeSpans = buildTypeSpans(type);
        spans.append(typeSpans);
        if (trailingSpace && !type.isEmpty()
            && !type.endsWith('*'_L1) && !type.endsWith('&'_L1)) {
            IR::SignatureSpan space;
            space.role = IR::SpanRole::Text;
            space.text = " "_L1;
            spans.append(space);
        }
    };
 
    IR::SignatureSpan nameSpan;
    nameSpan.role = IR::SpanRole::Name;
    nameSpan.text = node->name();
    nameSpan.href = resolveHref(hrefResolver, node, relative);
 
    if (node->isQmlProperty()) {
        const auto *pn = static_cast<const QmlPropertyNode *>(node);
        spans.append(nameSpan);
        appendText(" : "_L1);
        appendTypeSpans(pn->dataType(), false);
    } else if (node->isFunction(Genus::QML)) {
        const auto *func = static_cast<const FunctionNode *>(node);
        if (!func->returnType().isEmpty())
            appendTypeSpans(func->returnTypeString(), true);
        spans.append(nameSpan);
        appendText("("_L1);
        if (!func->parameters().isEmpty()) {
            const Parameters &parameters = func->parameters();
            for (int i = 0; i < parameters.count(); ++i) {
                if (i > 0)
                    appendText(", "_L1);
                QString pName = parameters.at(i).name();
                QString type = parameters.at(i).type();
                if (!pName.isEmpty()) {
                    appendTypeSpans(type, true);
                    IR::SignatureSpan paramSpan;
                    paramSpan.role = IR::SpanRole::Parameter;
                    paramSpan.text = pName;
                    spans.append(paramSpan);
                } else {
                    IR::SignatureSpan paramSpan;
                    paramSpan.role = IR::SpanRole::Parameter;
                    paramSpan.text = type;
                    spans.append(paramSpan);
                }
            }
        }
        appendText(")"_L1);
    } else {
        spans.append(nameSpan);
    }
 
    auto extras = buildExtraSpans(node, Section::Summary);
    if (!extras.isEmpty()) {
        appendText(" "_L1);
        spans.append(extras);
    }
 
    return spans;
}
 
static QString plainTextFromSpans(const QList<IR::SignatureSpan> &spans)
{
    QString result;
    for (const auto &span : spans)
        result += span.plainText();
    return result;
}
 
/*!
    \internal
    Build structured signature spans from Node data.
 
    This function produces a QList of SignatureSpan values that carry
    semantic roles (Type, Name, Parameter, Extra, and so on) for each
    element of a member's synopsis. It parallels what CppCodeMarker's
    markedUpSynopsis() and markedUpQmlItem() produce as tagged strings,
    but outputs structured IR spans instead.
 
    The \a style parameter controls level of detail: Summary includes
    virtual/override qualifiers, Details adds template declarations and
    parent prefixes, AllMembers uses a condensed format.
*/
QList<IR::SignatureSpan> buildSignatureSpans(const Node *node,
                                             const HrefResolver *hrefResolver,
                                             const Node *relative,
                                             Section::Style style)
{
    if (node->isQmlNode() && !node->isEnumType())
        return buildQmlItemSpans(node, hrefResolver, relative);
    return buildCppSynopsisSpans(node, hrefResolver, relative, style);
}
 
/*!
    \internal
    Extract a grouped all-members listing for a QML type.
 
    Constructs a Sections object from the QmlTypeNode, extracts
    allMembersSection().classNodesList() to group members by
    originating QML type, and builds AllMemberEntry items with
    QML-specific hints and property group nesting.
*/
static IR::AllMembersIR extractQmlAllMembersIR(const QmlTypeNode *qcn, const HrefResolver *hrefResolver)
{
    IR::AllMembersIR result;
    result.typeName = qcn->name();
    result.typeHref = resolveHref(hrefResolver, qcn, qcn);
    result.isQmlType = true;
 
    Sections sections(qcn);
    ClassNodesList &groupedMembers = sections.allMembersSection().classNodesList();
    if (groupedMembers.isEmpty())
        return result;
 
    const InclusionPolicy policy = Config::instance().createInclusionPolicy();
 
    std::function<IR::AllMemberEntry(Node *)> buildEntry = [&](Node *node) -> IR::AllMemberEntry {
        IR::AllMemberEntry entry;
        entry.signatureSpans = buildQmlItemSpans(node, hrefResolver, qcn);
        entry.signature = plainTextFromSpans(entry.signatureSpans);
        entry.href = resolveHref(hrefResolver, node, qcn);
 
        if (node->isQmlProperty()) {
            auto *qpn = static_cast<QmlPropertyNode *>(node);
            QStringList qmlHints = qpn->hints();
            if (qpn->isAttached() && !qmlHints.contains("attached"_L1))
                qmlHints << "attached"_L1;
            for (const auto &h : std::as_const(qmlHints))
                entry.hints.append(h);
        } else if (node->isAttached()) {
            entry.hints.append("attached"_L1);
        }
 
        if (node->isPropertyGroup()) {
            entry.isPropertyGroup = true;
            const auto *scn = static_cast<SharedCommentNode *>(node);
            for (auto *child : scn->collective()) {
                const NodeContext childContext = child->createContext();
                if (!InclusionFilter::isIncluded(policy, childContext))
                    continue;
                entry.children.append(buildEntry(child));
            }
        }
 
        return entry;
    };
 
    auto isVisible = [&policy](Node *node) {
        const NodeContext context = node->createContext();
        return InclusionFilter::isIncluded(policy, context)
            && !(node->isSharingComment() && node->sharedCommentNode()->isPropertyGroup());
    };
 
    for (const auto &[originType, nodes] : groupedMembers) {
        Q_ASSERT(originType);
        if (nodes.isEmpty())
            continue;
 
        IR::MemberGroup group;
        if (originType != qcn) {
            group.typeName = originType->name();
            group.typeHref = resolveHref(hrefResolver, originType, qcn);
        }
 
        for (auto *node : nodes) {
            if (isVisible(node))
                group.members.append(buildEntry(node));
        }
 
        result.memberGroups.append(group);
    }
 
    return result;
}
 
/*!
    \internal
    Extract a flat all-members listing for a C++ class or namespace.
 
    Constructs a Sections object from the aggregate, extracts
    allMembersSection().members(), builds AllMemberEntry for each
    visible member, and returns an AllMembersIR with isQmlType=false.
*/
static IR::AllMembersIR extractCppAllMembersIR(const Aggregate *aggregate, const HrefResolver *hrefResolver)
{
    IR::AllMembersIR result;
    result.typeName = aggregate->plainFullName();
    result.typeHref = resolveHref(hrefResolver, aggregate, aggregate);
    result.isQmlType = false;
 
    Sections sections(aggregate);
    const Section &allMembers = sections.allMembersSection();
    if (allMembers.isEmpty())
        return result;
 
    const InclusionPolicy policy = Config::instance().createInclusionPolicy();
 
    for (const auto *node : allMembers.members()) {
        if (node->name().isEmpty())
            continue;
        const NodeContext context = node->createContext();
        if (!InclusionFilter::isIncluded(policy, context))
            continue;
        if (node->isFunction()
            && static_cast<const FunctionNode *>(node)->isIgnored())
            continue;
 
        IR::AllMemberEntry entry;
        entry.signatureSpans = buildSignatureSpans(node, hrefResolver, aggregate, Section::AllMembers);
        entry.signature = plainTextFromSpans(entry.signatureSpans);
        entry.href = resolveHref(hrefResolver, node, aggregate);
        result.members.append(entry);
    }
 
    return result;
}
 
/*!
    \internal
    Extract all-members IR for a page node.
 
    Dispatches to the QML or C++ extraction function based on the page
    type. Returns std::nullopt for page types that don't have member
    listing pages (generic pages, QML basic types) or when the listing
    would be empty.
*/
std::optional<IR::AllMembersIR> extractAllMembersIR(const PageNode *pn, const HrefResolver *hrefResolver)
{
    if (pn->isQmlType()) {
        const auto *qcn = static_cast<const QmlTypeNode *>(pn);
        if (qcn->isQmlBasicType())
            return std::nullopt;
        auto result = extractQmlAllMembersIR(qcn, hrefResolver);
        bool hasMember = false;
        for (const auto &group : std::as_const(result.memberGroups)) {
            if (!group.members.isEmpty()) {
                hasMember = true;
                break;
            }
        }
        if (!hasMember)
            return std::nullopt;
        return result;
    }
 
    if (pn->isAggregate() && (pn->isClassNode() || pn->isNamespace())) {
        const auto *aggregate = static_cast<const Aggregate *>(pn);
        auto result = extractCppAllMembersIR(aggregate, hrefResolver);
        if (result.members.isEmpty())
            return std::nullopt;
        return result;
    }
 
    return std::nullopt;
}
 
/*!
    \internal
    Extract navigation metadata from a PageNode.
 
    Reads navigation configuration values (homepage, landingpage,
    cppclassespage, qmltypespage) and the node's position in the
    documentation tree to produce a breadcrumb chain, sequential
    links (previous/next/start), and the configured TOC depth.
 
    The breadcrumb chain follows page-type-specific logic ported
    from HtmlGenerator::generateNavigationBar(): static chain
    entries for API reference pages (class, QML type), a
    navigationParent() walk for generic pages with a 16-item
    circular reference cutoff, and a fallback to the first group
    page when no navigation parent exists.
 
    Sequential links come from the node's pre-populated link map,
    set by QDocDatabase::updateNavigation() before generation runs.
*/
IR::NavigationData extractNavigationData(const PageNode *pn, const HrefResolver *hrefResolver)
{
    IR::NavigationData nav;
    const Config &config = Config::instance();
    QDocDatabase *qdb = QDocDatabase::qdocDB();
 
    const QString navDot = CONFIG_NAVIGATION + Config::dot;
    const QString homepage = config.get(navDot + CONFIG_HOMEPAGE).asString();
    const QString hometitle = config.get(navDot + CONFIG_HOMETITLE).asString(homepage);
    const QString landingpage = config.get(navDot + CONFIG_LANDINGPAGE).asString();
    const QString landingtitle = config.get(navDot + CONFIG_LANDINGTITLE).asString(landingpage);
    const QString cppclassespage = config.get(navDot + CONFIG_CPPCLASSESPAGE).asString();
    const QString cppclassestitle = config.get(navDot + CONFIG_CPPCLASSESTITLE).asString("C++ Classes"_L1);
    const QString qmltypespage = config.get(navDot + CONFIG_QMLTYPESPAGE).asString();
    const QString qmltypestitle = config.get(navDot + CONFIG_QMLTYPESTITLE).asString("QML Types"_L1);
 
    const QString pageTitle = pn->title();
    using CrumbState = IR::NavigationData::CrumbState;
 
    auto resolveCrumb = [&](const QString &targetName)
            -> std::pair<QString, CrumbState> {
        const Node *target = qdb->findNodeForTarget(targetName, pn);
        if (!target)
            return {{}, CrumbState::Unresolved};
        if (target == pn)
            return {{}, CrumbState::Current};
        return {resolveHref(hrefResolver, target, pn), CrumbState::Link};
    };
 
    if (!homepage.isEmpty()) {
        auto [href, state] = resolveCrumb(homepage);
        if (state == CrumbState::Current)
            return nav;
        nav.breadcrumbs.append({hometitle, std::move(href), state});
    }
 
    if (!landingpage.isEmpty()) {
        auto [href, state] = resolveCrumb(landingpage);
        if (state != CrumbState::Current)
            nav.breadcrumbs.append({landingtitle, std::move(href), state});
    }
 
    if (pn->isClassNode()) {
        const bool hasClassesCrumb = !cppclassespage.isEmpty() && !cppclassestitle.isEmpty();
        if (hasClassesCrumb) {
            auto [href, state] = resolveCrumb(cppclassespage);
            nav.breadcrumbs.append({cppclassestitle, std::move(href), state});
        }
 
        const auto *moduleNode = qdb->getModuleNode(pn);
        QString moduleState;
        if (moduleNode && !moduleNode->state().isEmpty())
            moduleState = QStringLiteral(" (%1)").arg(moduleNode->state());
 
        if (!pn->physicalModuleName().isEmpty() && moduleNode
            && (!moduleState.isEmpty() || moduleNode->title() != cppclassespage)) {
            const QString moduleText = hasClassesCrumb || moduleNode->title().isEmpty()
                    ? moduleNode->name() : moduleNode->title();
            nav.breadcrumbs.append({moduleText + moduleState,
                                    resolveHref(hrefResolver, moduleNode, pn),
                                    CrumbState::Link});
        }
        nav.breadcrumbs.append({pn->name(), {}, CrumbState::Current});
    } else if (pn->isQmlType()) {
        const bool hasTypesCrumb = !qmltypespage.isEmpty() && !qmltypestitle.isEmpty();
        if (hasTypesCrumb) {
            auto [href, state] = resolveCrumb(qmltypespage);
            nav.breadcrumbs.append({qmltypestitle, std::move(href), state});
        }
 
        const auto *moduleNode = qdb->getModuleNode(pn);
        QString moduleState;
        if (moduleNode && !moduleNode->state().isEmpty())
            moduleState = QStringLiteral(" (%1)").arg(moduleNode->state());
 
        if (moduleNode
            && (!moduleState.isEmpty() || moduleNode->title() != qmltypespage)) {
            const QString moduleText = hasTypesCrumb || moduleNode->title().isEmpty()
                    ? moduleNode->name() : moduleNode->title();
            nav.breadcrumbs.append({moduleText + moduleState,
                                    resolveHref(hrefResolver, moduleNode, pn),
                                    CrumbState::Link});
        }
        nav.breadcrumbs.append({pn->name(), {}, CrumbState::Current});
    } else {
        auto currentNode = pn;
        std::deque<const Node *> navNodes;
        qsizetype navItems = 0;
        while (currentNode->navigationParent() && ++navItems < 16) {
            if (std::find(navNodes.cbegin(), navNodes.cend(),
                          currentNode->navigationParent()) == navNodes.cend())
                navNodes.push_front(currentNode->navigationParent());
            currentNode = currentNode->navigationParent();
        }
        if (navNodes.empty()) {
            const QStringList groups = pn->groupNames();
            for (const auto &groupName : groups) {
                const auto *groupNode = qdb->findNodeByNameAndType(
                        QStringList{groupName}, &Node::isGroup);
                if (groupNode && !groupNode->title().isEmpty()) {
                    navNodes.push_front(groupNode);
                    break;
                }
            }
        }
        for (const auto *navNode : navNodes) {
            if (navNode->isPageNode())
                nav.breadcrumbs.append({navNode->title(),
                                        resolveHref(hrefResolver, navNode, pn),
                                        CrumbState::Link});
        }
        if (!nav.breadcrumbs.isEmpty())
            nav.breadcrumbs.append({pageTitle, {}, CrumbState::Current});
    }
 
    const auto &linkMap = pn->links();
    if (linkMap.contains(Node::PreviousLink)) {
        const auto &linkPair = linkMap[Node::PreviousLink];
        const Node *target = qdb->findNodeForTarget(linkPair.first, pn);
        QString href;
        QString title;
        if (target && target != pn) {
            href = resolveHref(hrefResolver, target, pn);
            title = (linkPair.first == linkPair.second && !target->title().isEmpty())
                    ? target->title() : linkPair.second;
        } else {
            href = linkPair.first;
            title = linkPair.second;
        }
        nav.previousLink = IR::NavigationData::LinkEntry{title, href};
    }
    if (linkMap.contains(Node::NextLink)) {
        const auto &linkPair = linkMap[Node::NextLink];
        const Node *target = qdb->findNodeForTarget(linkPair.first, pn);
        QString href;
        QString title;
        if (target && target != pn) {
            href = resolveHref(hrefResolver, target, pn);
            title = (linkPair.first == linkPair.second && !target->title().isEmpty())
                    ? target->title() : linkPair.second;
        } else {
            href = linkPair.first;
            title = linkPair.second;
        }
        nav.nextLink = IR::NavigationData::LinkEntry{title, href};
    }
    if (linkMap.contains(Node::StartLink)) {
        const auto &linkPair = linkMap[Node::StartLink];
        const Node *target = qdb->findNodeForTarget(linkPair.first, pn);
        QString href;
        QString title;
        if (target && target != pn) {
            href = resolveHref(hrefResolver, target, pn);
            title = (linkPair.first == linkPair.second && !target->title().isEmpty())
                    ? target->title() : linkPair.second;
        } else {
            href = linkPair.first;
            title = linkPair.second;
        }
        nav.startLink = IR::NavigationData::LinkEntry{title, href};
    }
 
    const QString formatDot = "HTML"_L1 + Config::dot;
    nav.tocDepth = config.get(formatDot + "tocdepth"_L1).asInt();
 
    return nav;
}
 
} // namespace NodeExtractor
 
QT_END_NAMESPACE