hrefresolver.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 "hrefresolver.h"
 
#ifdef QDOC_TEMPLATE_GENERATOR_ENABLED
 
#include "anchorid.h"
#include "collectionnode.h"
#include "inclusionfilter.h"
#include "outputcontext.h"
#include "qmltypenode.h"
#include "tree.h"
#include "utilities.h"
 
#include <QtCore/qdir.h>
#include <QtCore/qfileinfo.h>
 
QT_BEGIN_NAMESPACE
 
/*!
    \struct HrefResolverConfig
    \internal
    \brief Configuration for HrefResolver URL computation.
 
    The non-owning \c context pointer is the single source of truth for
    output layout (project name, file extension, per-genus prefixes and
    suffixes, subdir usage, diagnostic gating). It must outlive the
    HrefResolver.
 
    The \c cleanRefFn callback sanitizes anchor references. It
    corresponds to Generator::cleanRef() in the legacy path.
 
    The \c qmlTypeContextFn callback returns the current QML type
    being documented, enabling property inheritance resolution for
    abstract QML types. An empty callback disables this resolution.
    hrefForNode() prefers the \c relative page when it is a QML type,
    because that page is the member's rendered documentation owner and
    the callback may hold stale state from another generator.
*/
 
/*!
    \class HrefResolver
    \internal
    \brief Computes URLs for documentation nodes without Generator dependencies.
 
    Not thread-safe: the mutable fileBase cache is written from const
    methods. Create one instance per thread or synchronize externally.
*/
 
HrefResolver::HrefResolver(const HrefResolverConfig &config)
    : m_config(config)
{
}
 
/*!
    Computes the filename stem for \a node without mutating the node.
    Results are cached in m_fileBaseCache to avoid recomputation.
 
    This mirrors Generator::fileBase() but uses an external QHash cache
    instead of const_cast on the Node.
 
    Like HtmlGenerator::fileBase(), the stem of a deprecated
    non-aggregate node (a member or a page) carries an "-obsolete"
    suffix. Deprecated members are documented on their aggregate's
    obsolete sub-page, so links to them must use the suffixed name to
    resolve there. Aggregates keep their own page name.
*/
QString HrefResolver::fileBase(const Node *node) const
{
    const bool obsoleteFileBase = !node->isAggregate() && node->isDeprecated();
 
    if (!node->isPageNode() && !node->isCollectionNode()) {
        node = node->parent();
        if (!node)
            return {};
    }
 
    QString result;
    if (node->hasFileNameBase()) {
        result = node->fileNameBase();
    } else {
        auto it = m_fileBaseCache.constFind(node);
        if (it != m_fileBaseCache.constEnd()) {
            result = it.value();
        } else {
            const OutputContext *ctx = m_config.context;
            result = Utilities::computeFileBase(
                    node, ctx->project,
                    [ctx](const Node *n) { return ctx->outputPrefix(n->genus()); },
                    [ctx](const Node *n) { return ctx->outputSuffix(n->genus()); });
            m_fileBaseCache.insert(node, result);
        }
    }
 
    if (obsoleteFileBase)
        result += "-obsolete"_L1;
    return result;
}
 
/*!
    Computes the output filename for \a node. Returns the node's
    explicit URL if one is set, otherwise constructs a filename
    from fileBase() and the configured file extension.
 
    This mirrors Generator::fileName() without depending on a
    Generator instance.
*/
QString HrefResolver::fileName(const Node *node) const
{
    if (!node->url().isEmpty())
        return node->url();
 
    const auto base = fileBase(node);
    if (base.isEmpty())
        return {};
 
    if (node->isTextPageNode() && !node->isCollectionNode()) {
        QFileInfo originalName(node->name());
        QString suffix = originalName.suffix();
        if (!suffix.isEmpty() && suffix != "html"_L1)
            return base + '.'_L1 + suffix;
    }
 
    return base + '.'_L1 + m_config.context->fileExtension;
}
 
/*!
    Computes the anchor fragment for \a node based on its type.
    Returns an empty string for page-level nodes that don't need
    anchors.
 
    Delegates to the free function computeAnchorId() for node-type
    dispatch, then applies the configured cleanRefFn for sanitization.
    This keeps the shared anchor logic generator-agnostic while
    allowing each caller to control cleanup policy.
*/
QString HrefResolver::anchorForNode(const Node *node) const
{
    const QString ref = computeAnchorId(node);
    if (ref.isEmpty())
        return ref;
    return m_config.cleanRefFn ? m_config.cleanRefFn(ref) : ref;
}
 
/*!
    Computes a relative URL for \a node, relative to \a relative.
    Returns the URL as a QString on success, or an HrefSuppressReason
    explaining why linking should be suppressed.
 
    External pages (declared via \c \\externalpage) pass through
    unchanged, since their URL points by design at a resource outside
    the current documentation set. Every other reference — including
    URLs loaded from a dependency's \c .index file or authored with an
    explicit \c \\url that names an absolute address such as
    \c https://doc.qt.io/... — is reduced to a bare filename stem and
    then prefixed with whatever relative path reaches the target
    module's output directory from the current page's output
    directory. The prefix is derived from OutputContext and the two
    nodes' trees, not from a hardcoded \c ../<module>/ pattern, so it
    comes out correct regardless of whether the qdocconf uses
    per-module subdirs, a format subdirectory, or both.
*/
HrefResult HrefResolver::hrefForNode(const Node *node, const Node *relative) const
{
    if (node == nullptr)
        return HrefSuppressReason::NullNode;
 
    const bool hasExplicitUrl = !node->url().isEmpty();
    if (hasExplicitUrl && node->isExternalPage())
        return node->url();
 
    // An explicit URL arrives with a directory prefix baked in by the
    // reader that produced it (qdocindexfiles prepends ../<module>/).
    // That prefix encodes one specific layout's depth assumption and
    // is wrong for any other layout, so discard it and recompute from
    // the current output paths below.
    QString fn = hasExplicitUrl
            ? node->url().section('/'_L1, -1)
            : fileName(node);
    // Strip any anchor from an explicit URL: anchorForNode below is the
    // single source of truth for the final anchor. Without this, members
    // of cross-tree pages get the baked anchor preserved and a fresh
    // anchor appended, producing href values like
    // `qwindow.html#devicePixelRatio#devicePixelRatio`.
    if (hasExplicitUrl) {
        const qsizetype hashIndex = fn.indexOf('#'_L1);
        if (hashIndex >= 0)
            fn.truncate(hashIndex);
    }
    if (fn.isEmpty())
        return HrefSuppressReason::NoFileBase;
 
    // A cross-module collection placeholder carries content authored in
    // another module; its location identity (tree()) points at the
    // consumer module, but its content-origin identity lives on the
    // resolvedPhysicalModuleName field set during mergeCollections.
    // Treat it the same as an index-loaded node: bypass InclusionFilter
    // and fire the cross-module prefix.
    const bool isCrossModulePlaceholder = node->isCollectionNode()
            && !static_cast<const CollectionNode *>(node)
                       ->resolvedPhysicalModuleName().isEmpty();
 
    // Index-loaded nodes carry partial metadata (e.g., a placeholder
    // Doc), so InclusionFilter can reject upstream-published entities
    // on synthetic flags. Skip the check for them. Cross-module
    // collection placeholders share that semantic without the
    // isIndexNode flag, so admit them too.
    if (!node->isIndexNode() && !isCrossModulePlaceholder) {
        const NodeContext context = node->createContext();
        if (!InclusionFilter::isIncluded(m_config.inclusionPolicy, context))
            return HrefSuppressReason::ExcludedByPolicy;
    }
 
    if (!hasExplicitUrl && node->parent() && node->parent()->isQmlType()
        && node->parent()->isAbstract()) {
        // The legacy generators record the QML type they are generating in
        // Generator's mutable state and expose it through qmlTypeContextFn.
        // Template generators never establish that state, so prefer the
        // page being rendered when it is a QML type, and fall back to the
        // callback for contexts the callback owns (for instance legacy
        // cross-format runs).
        const QmlTypeNode *qmlContext = nullptr;
        if (relative && relative->isQmlType())
            qmlContext = static_cast<const QmlTypeNode *>(relative);
        else if (m_config.qmlTypeContextFn)
            qmlContext = m_config.qmlTypeContextFn();
        if (qmlContext) {
            if (qmlContext->inherits(node->parent())) {
                fn = fileName(qmlContext);
                // fileBase() gives a deprecated member an "-obsolete"
                // suffix so it resolves to the type's obsolete sub-page.
                // The remap above replaced that stem with the type's main
                // page name, so re-apply the suffix when the member is
                // deprecated and the target is a computed name rather than
                // an explicit \url.
                if (!node->isAggregate() && node->isDeprecated()
                        && qmlContext->url().isEmpty()) {
                    const QString ext = '.'_L1 + m_config.context->fileExtension;
                    fn.chop(ext.length());
                    fn += "-obsolete"_L1 + ext;
                }
            } else if (node->parent()->isInternal() && !m_config.context->noLinkErrors) {
                node->doc().location().warning(
                        u"Cannot link to property in internal type '%1'"_s
                                .arg(node->parent()->name()));
                return HrefSuppressReason::InternalAbstractQml;
            }
        }
    }
 
    QString link = fn;
 
    if (!node->isPageNode() || node->isPropertyGroup()) {
        QString ref = anchorForNode(node);
        if (relative && fn == fileName(relative) && ref == anchorForNode(relative))
            return HrefSuppressReason::SameFileAnchor;
 
        link += '#'_L1;
        link += ref;
    }
 
    if (relative && (node != relative) && !node->isExternalPage()
        && (node->isIndexNode() || isCrossModulePlaceholder
            || node->tree() != relative->tree())) {
        link.prepend(crossModulePrefix(node, relative));
    }
 
    return link;
}
 
/*!
    \internal
    Returns a relative-path prefix (ending in \c /) that reaches \a
    target's output directory from \a source's output directory, or
    an empty string when the two share a directory.
 
    The current page's output directory is the OutputContext's \c
    outputDir. The target's output directory is derived by locating
    the current module's name as a segment in that path and swapping
    in the target module's name. If the current module's name isn't
    present — a flat layout where multiple modules render into the
    same directory — source and target share a directory and no
    prefix is needed.
*/
QString HrefResolver::crossModulePrefix(const Node *target, const Node *source) const
{
    const QString &sourceDir = m_config.context->outputDir.path();
    const QString currentSegment = '/'_L1 + source->tree()->physicalModuleName() + '/'_L1;
    const qsizetype moduleIndex = sourceDir.indexOf(currentSegment);
    if (moduleIndex < 0)
        return {};
 
    // Cross-module collection placeholders live in the consumer tree but
    // mirror content from another. Prefer the recorded upstream module
    // name so the computed prefix reflects the content origin instead of
    // the placeholder's location.
    QString targetModuleName;
    if (target->isCollectionNode()) {
        const auto *cn = static_cast<const CollectionNode *>(target);
        targetModuleName = cn->resolvedPhysicalModuleName();
    }
    if (targetModuleName.isEmpty())
        targetModuleName = target->tree()->physicalModuleName();
    const QString targetSegment = '/'_L1 + targetModuleName + '/'_L1;
    QString targetDir = sourceDir;
    targetDir.replace(moduleIndex, currentSegment.size(), targetSegment);
 
    const QString relPath = QDir(sourceDir).relativeFilePath(targetDir);
    if (relPath.isEmpty() || relPath == "."_L1)
        return {};
    return relPath + '/'_L1;
}
 
QT_END_NAMESPACE
 
#endif // QDOC_TEMPLATE_GENERATOR_ENABLED