linkresolver.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
 
#ifdef QDOC_TEMPLATE_GENERATOR_ENABLED
 
#include "linkresolver.h"
 
#include "genustypes.h"
#include "hrefresolver.h"
#include "ir/contentblock.h"
#include "location.h"
#include "node.h"
#include "qdocdatabase.h"
#include "qdoclogging.h"
 
using namespace Qt::Literals::StringLiterals;
 
QT_BEGIN_NAMESPACE
 
static Genus genusFromString(const QString &s)
{
    if (s == "cpp"_L1)
        return Genus::CPP;
    if (s == "qml"_L1)
        return Genus::QML;
    if (s == "doc"_L1)
        return Genus::DOC;
    if (s == "api"_L1)
        return Genus::API;
    return Genus::DontCare;
}
 
static bool isBrokenAutolink(const IR::InlineContent &inline_)
{
    return inline_.type == IR::InlineType::Link
            && inline_.link.has_value()
            && inline_.link->state == IR::LinkState::Broken
            && inline_.link->origin == IR::LinkOrigin::Auto;
}
 
/*!
    Constructs a LinkResolver that uses \a qdb for node lookup,
    \a hrefResolver for URL computation, and \a config for warning
    policy.
*/
LinkResolver::LinkResolver(QDocDatabase *qdb, const HrefResolver &hrefResolver,
                           const LinkResolverConfig &config)
    : m_qdb(qdb), m_hrefResolver(hrefResolver), m_config(config)
{
}
 
/*!
    Walks \a blocks and resolves all unresolved Link inlines in place.
 
    \a context.semantic is the node whose documentation the content was
    authored in: for a page body that is the page node; for a detail
    member body or see-also list that is the authored member, or the
    SharedCommentNode for copied shared comment text. Node lookup,
    deprecated-link suppression, and warning attribution use it. A null
    semantic falls back to \a context.page, the output page node.
 
    \a context.page is the output page node that renders the content.
    URL computation through HrefResolver and cross-module relative URLs
    use it, so rendered hrefs always stay relative to the rendered page
    even when the semantic context is a member inside that page.
 
    This must be called after ContentBuilder produces the block tree
    and before rendering.
*/
void LinkResolver::resolve(QList<IR::ContentBlock> &blocks, Context context)
{
    if (!context.semantic)
        context.semantic = context.page;
    for (auto &block : blocks)
        resolveBlock(block, context);
}
 
/*!
    Resolves links within a single \a block by processing its inline
    content and recursing into child blocks.
*/
void LinkResolver::resolveBlock(IR::ContentBlock &block, const Context &context)
{
    resolveInlines(block.inlineContent, context);
    for (auto &child : block.children)
        resolveBlock(child, context);
}
 
/*!
    Iterates \a inlines and resolves each Link element. Also recurses
    into children of all inline elements since Link inlines can contain
    nested formatting (such as Bold or Italic).
*/
void LinkResolver::resolveInlines(QList<IR::InlineContent> &inlines, const Context &context)
{
    for (auto &inline_ : inlines) {
        if (inline_.type == IR::InlineType::Link && !inline_.href.isEmpty())
            resolveLink(inline_, context);
 
        if (isBrokenAutolink(inline_)) {
            qCDebug(lcQdoc) << "Autolink degraded to text:" << inline_.href;
            inline_.type = IR::InlineType::Text;
            inline_.text = inline_.plainText();
            inline_.href.clear();
            inline_.children.clear();
            inline_.link.reset();
            inline_.attributes = QJsonObject();
            continue;
        }
 
        if (!inline_.children.isEmpty())
            resolveInlines(inline_.children, context);
    }
}
 
/*!
    Core resolution logic for a single Link \a link. Mirrors the behavior
    of XmlGenerator::getLink() and XmlGenerator::getAutoLink():
 
    \list
    \li External URLs (http, https, ftp, file, mailto) are marked without
        node lookup.
    \li Node lookup uses the \a context.semantic node as the search
        context, and genus and module metadata from ContentBuilder when
        available. Explicit links carry genus scoping (CPP, QML) and
        module names for tree-scoped search. Autolinks fall back to
        forest-wide search with DontCare genus.
    \li Deprecated targets suppress autolinks when the semantic node isn't
        deprecated; explicit \\l and \\sa links keep the author's reference.
    \li HrefResolver computes the URL relative to the \a context.page node
        and returns an HrefResult variant: a URL on success, or an
        HrefSuppressReason (self-link, policy exclusion, etc.) that maps
        to LinkState::Suppressed.
    \li Unresolvable links emit warnings controlled by LinkResolverConfig.
    \endlist
 
    The \a context.semantic node provides the context for node lookup,
    deprecation behavior, and warning source location; the \a context.page
    node provides the context for URL computation.
*/
void LinkResolver::resolveLink(IR::InlineContent &link, const Context &context)
{
    Q_ASSERT(link.link.has_value());
 
    if (link.link->state != IR::LinkState::Unresolved)
        return;
 
    const QString &target = link.href;
 
    // External URL -- no resolution needed.
    if (target.startsWith("http:"_L1) || target.startsWith("https:"_L1)
        || target.startsWith("ftp:"_L1) || target.startsWith("file:"_L1)
        || target.startsWith("mailto:"_L1)) {
        link.link->state = IR::LinkState::External;
        return;
    }
 
    // Intra-page anchor link -- references a section heading or member
    // anchor within the same page. These don't go through node lookup.
    if (target.startsWith('#'_L1)) {
        link.link->state = IR::LinkState::Resolved;
        return;
    }
 
    // Use genus and module metadata from ContentBuilder when available.
    // Explicit links (LinkAtom) carry genus and module; autolinks don't.
    const Genus genus = genusFromString(
            link.attributes.value("linkGenus"_L1).toString());
    const QString &moduleName =
            link.attributes.value("linkModule"_L1).toString();
    QString ref;
    const Node *targetNode =
            m_qdb->findNodeForTarget(target, context.semantic, genus, moduleName, &ref);
 
    if (!targetNode) {
        const auto reportAt = [&](const QString &message) {
            if (link.link->sourceLocation) {
                Location loc(link.link->sourceLocation->filePath);
                loc.setLineNo(link.link->sourceLocation->lineNo);
                loc.warning(message);
            } else if (context.semantic) {
                context.semantic->doc().location().warning(message);
            }
        };
        if (link.link->origin == IR::LinkOrigin::Auto) {
            if (m_config.autolinkErrors)
                reportAt(u"Can't autolink to '%1'"_s.arg(target));
        } else {
            if (!m_config.noLinkErrors)
                reportAt(u"Can't link to '%1'"_s.arg(target));
        }
 
        link.link->state = IR::LinkState::Broken;
        link.href.clear();
        return;
    }
 
    // Deprecated node suppression: autolinks to deprecated nodes are
    // suppressed when the semantic node isn't deprecated, unless the link
    // originates from within the deprecated node's own documentation
    if (link.link->origin == IR::LinkOrigin::Auto
        && targetNode->isDeprecated() && context.semantic
        && context.semantic->parent() != targetNode && !context.semantic->isDeprecated()) {
        link.href.clear();
        link.link->state = IR::LinkState::Suppressed;
        return;
    }
 
    // Compute URL via HrefResolver relative to the rendered page.
    // Cross-tree references reach LinkResolver carrying a URL baked at
    // .index-load time using Generator::s_outSubdir, which is only
    // updated by Generator-derived pipelines (HTML, DocBook).
    // TemplateGenerator doesn't touch that static, so its baked URLs have
    // the wrong relative depth for its layout. Route those references
    // through hrefForNode's strip-and-recompute path so the emitted href
    // matches the current OutputContext.
    QString url = targetNode->url();
    const bool isCrossTreeIndexLoaded = context.page && !targetNode->isExternalPage()
            && (targetNode->isIndexNode() || targetNode->tree() != context.page->tree());
    if (url.isNull() || (isCrossTreeIndexLoaded && !url.isEmpty())) {
        auto result = m_hrefResolver.hrefForNode(targetNode, context.page);
        if (std::get_if<HrefSuppressReason>(&result)) {
            link.href.clear();
            link.link->state = IR::LinkState::Suppressed;
            return;
        }
        url = std::get<QString>(std::move(result));
    } else if (url.isEmpty()) {
        link.href.clear();
        link.link->state = IR::LinkState::Ignored;
        return;
    }
 
    // When the target designates a section title or named anchor within the
    // page, replace any member anchor the URL may already carry with the one
    // the lookup computed. Mirrors XmlGenerator::getAutoLink().
    if (!ref.isEmpty()) {
        const qsizetype hashIndex = url.lastIndexOf(u'#');
        if (hashIndex != -1)
            url.truncate(hashIndex);
        url += u'#' + ref;
    }
 
    link.href = url;
    link.link->state = IR::LinkState::Resolved;
}
 
QT_END_NAMESPACE
 
#endif // QDOC_TEMPLATE_GENERATOR_ENABLED