contentbuilder.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 "contentbuilder.h"
 
#include "../atom.h"
 
QT_BEGIN_NAMESPACE
 
using namespace Qt::Literals::StringLiterals;
 
namespace IR {
 
/*!
    \class IR::ContentBuilder
    \internal
    \brief Converts Atom chains to QList<IR::ContentBlock> trees.
 
    ContentBuilder walks a linked list of Atom nodes (QDoc's internal
    documentation representation) and produces a structured tree of
    ContentBlock and InlineContent values suitable for template rendering.
 
    Handled atom types:
    \list
        \li ParaLeft, ParaRight -- Paragraph blocks.
        \li String -- Text inline content.
        \li C -- Inline code spans.
        \li Code, CodeBad, Qml -- Code blocks with language attribute.
        \li SectionLeft, SectionRight -- Section containers.
        \li SectionHeadingLeft, SectionHeadingRight -- Section headings with
            level.
        \li FormattingLeft, FormattingRight -- Bold, italic, teletype,
            underline, subscript, superscript, parameter, uicontrol, trademark,
            link, index, notranslate, span.
        \li ListLeft, ListRight -- Ordered and unordered lists.
        \li ListItemLeft, ListItemRight -- List items.
        \li ListItemNumber -- List start number metadata.
        \li NoteLeft, NoteRight -- Note admonition blocks.
        \li WarningLeft, WarningRight -- Warning admonition blocks.
        \li BriefLeft, BriefRight -- Brief exclusion (skipped in body).
        \li Link, NavLink -- Explicit links with unresolved target.
        \li AutoLink, NavAutoLink -- Auto-linked type names with unresolved
            target.
        \li BR -- Line break inline.
        \li HR -- Horizontal rule block.
        \li Nop -- No-operation (skipped).
        \li BaseName -- No-operation (skipped).
        \li TableLeft, TableRight -- Table containers with style attribute.
        \li TableHeaderLeft, TableHeaderRight -- Table header rows.
        \li TableRowLeft, TableRowRight -- Table data rows.
        \li TableItemLeft, TableItemRight -- Table cells with optional
            colspan/rowspan.
        \li ListTagLeft, ListTagRight -- Value list tag items (ListItem
            blocks).
        \li SinceTagLeft, SinceTagRight -- Version tag items (skipped).
        \li AnnotatedList -- Placeholder Div.
        \li GeneratedList -- Placeholder Div.
    \endlist
 
    Format-conditional atoms (FormatIf, FormatElse, FormatEndif) are
    skipped unconditionally. The template generator builds a
    format-agnostic IR that serves all output formats from a single
    build pass.
 
    ContentBuilder depends only on Atom (for reading the chain) and IR types
    (for producing output).
 
    \sa ContentBlock, InlineContent
*/
 
static InlineType formattingToInlineType(const QString &formatting)
{
    if (formatting == ATOM_FORMATTING_BOLD)
        return InlineType::Bold;
    if (formatting == ATOM_FORMATTING_ITALIC)
        return InlineType::Italic;
    if (formatting == ATOM_FORMATTING_TELETYPE)
        return InlineType::Teletype;
    if (formatting == ATOM_FORMATTING_UNDERLINE)
        return InlineType::Underline;
    if (formatting == ATOM_FORMATTING_SUBSCRIPT)
        return InlineType::Subscript;
    if (formatting == ATOM_FORMATTING_SUPERSCRIPT)
        return InlineType::Superscript;
    if (formatting == ATOM_FORMATTING_PARAMETER)
        return InlineType::Parameter;
    return InlineType::Text;
}
 
/*!
    Walks the atom chain starting at \a firstAtom and returns a list
    of ContentBlock trees representing the structured documentation body.
 
    Returns an empty list if \a firstAtom is \nullptr.
 
    The builder is reset before processing, so a single ContentBuilder
    instance can be reused for multiple build() calls.
*/
QList<ContentBlock> ContentBuilder::build(const Atom *firstAtom)
{
    m_result.clear();
    m_blockPath.clear();
    m_inlinePath.clear();
    m_inlineBaseDepths.clear();
    m_inBrief = false;
    m_inLink = false;
 
    if (!firstAtom)
        return {};
 
    processAtoms(firstAtom);
 
    // Malformed atom chain recovery: auto-close remaining blocks in
    // release builds, assert in debug to surface the source error.
    if (Q_UNLIKELY(!m_blockPath.isEmpty())) {
        Q_ASSERT_X(false, "ContentBuilder::build",
                    "Unclosed blocks at end of atom chain");
        while (!m_blockPath.isEmpty())
            closeBlock();
    }
 
    Q_ASSERT(m_inlinePath.isEmpty());
    Q_ASSERT(m_inlineBaseDepths.isEmpty());
    Q_ASSERT(!m_inLink);
    Q_ASSERT(!m_inBrief);
 
    return m_result;
}
 
/*!
    Walks the full atom chain starting at \a atom, building the
    content tree. FormatIf..FormatEndif blocks are skipped
    unconditionally via skipFormatIfBlock(). Stray FormatElse and
    FormatEndif atoms outside any FormatIf context are ignored.
*/
void ContentBuilder::processAtoms(const Atom *atom)
{
    while (atom) {
        if (atom->type() == Atom::FormatIf) {
            atom = skipFormatIfBlock(atom);
            continue;
        }
        if (atom->type() == Atom::FormatElse || atom->type() == Atom::FormatEndif) {
            atom = atom->next();
            continue;
        }
        atom = dispatchAtom(atom);
        if (!atom)
            return;
        atom = atom->next();
    }
}
 
/*!
    Skips an entire FormatIf..FormatEndif block, including any nested
    FormatIf blocks and FormatElse branches. The scan only tracks
    FormatIf and FormatEndif for depth counting; all other atom types
    (including FormatElse) are treated as inert content and walked
    past without dispatch.
 
    The template generator builds a format-agnostic IR, so
    format-conditional content is unconditionally excluded.
 
    Returns a pointer to the atom after FormatEndif, or \nullptr if
    the chain ends before FormatEndif is found.
*/
const Atom *ContentBuilder::skipFormatIfBlock(const Atom *atom)
{
    Q_ASSERT(atom->type() == Atom::FormatIf);
    int depth = 1;
    atom = atom->next();
    while (atom && depth > 0) {
        if (atom->type() == Atom::FormatIf)
            ++depth;
        else if (atom->type() == Atom::FormatEndif)
            --depth;
        atom = atom->next();
    }
    return atom;
}
 
/*!
    Dispatches a single atom to the content model. Returns the last
    atom consumed — usually \a atom itself, but some atom types may
    consume subsequent atoms.
*/
const Atom *ContentBuilder::dispatchAtom(const Atom *atom)
{
    if (atom->type() == Atom::BriefLeft) {
        m_inBrief = true;
        return atom;
    }
    if (atom->type() == Atom::BriefRight) {
        m_inBrief = false;
        return atom;
    }
    if (m_inBrief)
        return atom;
 
    switch (atom->type()) {
 
    case Atom::ParaLeft:
        openBlock(BlockType::Paragraph);
        break;
 
    case Atom::ParaRight:
        closeBlock();
        break;
 
    case Atom::String:
        addLeafInline(InlineType::Text, atom->string());
        break;
 
    case Atom::C:
        addLeafInline(InlineType::Code, atom->string());
        break;
 
    case Atom::Code:
    case Atom::CodeBad:
    case Atom::Qml: {
        QJsonObject attrs;
        if (atom->type() == Atom::Qml) {
            attrs["language"_L1] = u"qml"_s;
        } else if (atom->type() == Atom::CodeBad) {
            attrs["language"_L1] = u"cpp"_s;
            attrs["bad"_L1] = true;
        } else if (atom->count() >= 2 && !atom->string(1).isEmpty()) {
            attrs["language"_L1] = atom->string(1);
        } else {
            attrs["language"_L1] = u"cpp"_s;
        }
 
        openBlock(BlockType::CodeBlock, attrs);
        addLeafInline(InlineType::Text, atom->string());
        closeBlock();
        break;
    }
 
    case Atom::AutoLink:
    case Atom::NavAutoLink: {
        // href values are not author-controlled. They are produced by QDoc
        // link resolution (\l, autolinks) against the node tree, or by
        // \image path handling. They don't contain arbitrary schemes (e.g.
        // javascript:). Only link text originates from user-authored docs
        // and must be HTML-escaped in templates.
        InlineContent link;
        link.type = InlineType::Link;
        link.href = atom->string();
        link.children.append({ InlineType::Text, atom->string(), {}, {}, {}, {} });
        addInline(std::move(link));
        break;
    }
 
    case Atom::Link:
    case Atom::NavLink: {
        if (Q_UNLIKELY(m_blockPath.isEmpty()))
            break;
 
        m_inLink = true;
 
        InlineContent link;
        link.type = InlineType::Link;
        link.href = atom->string();
 
        pushInlineContainer(std::move(link));
 
        // Link atoms are always followed by FormattingLeft("link");
        // skip it to avoid double-processing.
        if (atom->next() && atom->next()->type() == Atom::FormattingLeft
            && atom->next()->string() == ATOM_FORMATTING_LINK) {
            return atom->next();
        }
        break;
    }
 
    case Atom::FormattingLeft: {
        const QString &fmt = atom->string();
 
        if (fmt == ATOM_FORMATTING_INDEX || fmt.startsWith(u"span "_s))
            break;
 
        if (fmt == ATOM_FORMATTING_LINK)
            break;
 
        if (fmt == ATOM_FORMATTING_TRADEMARK || fmt == ATOM_FORMATTING_NOTRANSLATE)
            break;
 
        if (fmt == ATOM_FORMATTING_UICONTROL) {
            InlineContent bold;
            bold.type = InlineType::Bold;
            pushInlineContainer(std::move(bold));
            break;
        }
 
        InlineType type = formattingToInlineType(fmt);
        if (type == InlineType::Text)
            break;
 
        InlineContent container;
        container.type = type;
        pushInlineContainer(std::move(container));
        break;
    }
 
    case Atom::FormattingRight: {
        const QString &fmt = atom->string();
 
        if (fmt == ATOM_FORMATTING_LINK) {
            if (m_inLink) {
                const qsizetype base = m_inlineBaseDepths.isEmpty() ? 0 : m_inlineBaseDepths.last();
                if (m_inlinePath.size() > base) {
                    Q_ASSERT(resolveInline()->type == InlineType::Link);
                    m_inlinePath.removeLast();
                }
                m_inLink = false;
            }
            break;
        }
 
        if (fmt == ATOM_FORMATTING_INDEX || fmt == ATOM_FORMATTING_NOTRANSLATE
            || fmt.startsWith(u"span "_s) || fmt == ATOM_FORMATTING_TRADEMARK) {
            break;
        }
 
        const qsizetype base = m_inlineBaseDepths.isEmpty() ? 0 : m_inlineBaseDepths.last();
        if (m_inlinePath.size() > base)
            m_inlinePath.removeLast();
        break;
    }
 
    case Atom::SectionLeft:
        openBlock(BlockType::Section);
        break;
 
    case Atom::SectionRight:
        closeBlock();
        break;
 
    case Atom::SectionHeadingLeft: {
        QJsonObject attrs;
        attrs["level"_L1] = atom->string().toInt();
        openBlock(BlockType::SectionHeading, attrs);
        break;
    }
 
    case Atom::SectionHeadingRight:
        closeBlock();
        break;
 
    case Atom::ListLeft: {
        QJsonObject attrs;
        attrs["listType"_L1] = atom->string();
        openBlock(BlockType::List, attrs);
        break;
    }
 
    case Atom::ListRight:
        closeBlock();
        break;
 
    case Atom::ListItemLeft:
        openBlock(BlockType::ListItem);
        break;
 
    case Atom::ListItemRight:
        closeBlock();
        break;
 
    case Atom::ListItemNumber:
        // Start-number metadata is not yet represented in the IR.
        break;
 
    case Atom::NoteLeft:
        openBlock(BlockType::Note);
        break;
 
    case Atom::NoteRight:
        closeBlock();
        break;
 
    case Atom::WarningLeft:
        openBlock(BlockType::Warning);
        break;
 
    case Atom::WarningRight:
        closeBlock();
        break;
 
    case Atom::BR:
        addLeafInline(InlineType::LineBreak, {});
        break;
 
    case Atom::HR:
        openBlock(BlockType::HorizontalRule);
        closeBlock();
        break;
 
    case Atom::AnnotatedList: {
        QJsonObject attrs;
        attrs["annotatedList"_L1] = atom->string();
        openBlock(BlockType::Div, attrs);
        closeBlock();
        break;
    }
 
    case Atom::GeneratedList: {
        QJsonObject attrs;
        attrs["generatedList"_L1] = atom->string();
        openBlock(BlockType::Div, attrs);
        closeBlock();
        break;
    }
 
    case Atom::TableLeft: {
        QJsonObject attrs;
        const QString &style = atom->string();
        attrs["style"_L1] = style == "borderless"_L1 ? style : u"generic"_s;
        openBlock(BlockType::Table, attrs);
        break;
    }
 
    case Atom::TableRight:
        closeBlock();
        break;
 
    case Atom::TableHeaderLeft:
        openBlock(BlockType::TableHeaderRow);
        break;
 
    case Atom::TableHeaderRight:
        closeBlock();
        break;
 
    case Atom::TableRowLeft:
        openBlock(BlockType::TableRow);
        break;
 
    case Atom::TableRowRight:
        closeBlock();
        break;
 
    case Atom::TableItemLeft: {
        QJsonObject attrs;
        const QString &spec = atom->string();
        if (!spec.isEmpty()) {
            const auto parts = QStringView{spec}.split(u',');
            if (parts.size() >= 2) {
                int colspan = qMax(1, parts[0].toInt());
                int rowspan = qMax(1, parts[1].toInt());
                if (colspan > 1)
                    attrs["colspan"_L1] = colspan;
                if (rowspan > 1)
                    attrs["rowspan"_L1] = rowspan;
            }
        }
        openBlock(BlockType::TableCell, attrs);
        break;
    }
 
    case Atom::TableItemRight:
        closeBlock();
        break;
 
    case Atom::ListTagLeft:
        openBlock(BlockType::ListItem);
        break;
 
    case Atom::ListTagRight:
        closeBlock();
        break;
 
    case Atom::SinceTagLeft:
    case Atom::SinceTagRight:
        break;
 
    case Atom::Nop:
    case Atom::BaseName:
        break;
 
    default:
        break;
    }
    return atom;
}
 
/*!
    Opens a new block of type \a type with optional \a attrs.
 
    If the block path is empty, the block is added to the top-level
    result list. Otherwise it is added as a child of the current
    container block.
*/
void ContentBuilder::openBlock(BlockType type, QJsonObject attrs)
{
    ContentBlock block;
    block.type = type;
    block.attributes = std::move(attrs);
 
    m_inlineBaseDepths.append(m_inlinePath.size());
 
    if (m_blockPath.isEmpty()) {
        m_result.append(std::move(block));
        m_blockPath.append(m_result.size() - 1);
    } else {
        auto *parent = resolveBlock();
        parent->children.append(std::move(block));
        m_blockPath.append(parent->children.size() - 1);
    }
}
 
/*!
    Closes the current block by popping it from the block path.
 
    Verifies that the inline path depth matches the depth recorded
    when this block was opened (all formatting pairs balanced).
    In release builds, the inline path is restored to the expected
    depth as a safety measure against malformed atom chains.
*/
void ContentBuilder::closeBlock()
{
    if (!m_blockPath.isEmpty()) {
        if (Q_UNLIKELY(m_inlineBaseDepths.isEmpty())) {
            // openBlock() always pushes a base depth, so this indicates
            // a logic error in the builder. Assert in debug; recover in
            // release by clearing all state.
            Q_ASSERT_X(false, "ContentBuilder::closeBlock",
                        "m_inlineBaseDepths empty with non-empty m_blockPath");
            m_inlinePath.clear();
            m_blockPath.clear();
            m_inlineBaseDepths.clear();
            m_inLink = false;
            return;
        }
        const qsizetype expectedDepth = m_inlineBaseDepths.last();
        if (m_inLink && m_inlinePath.size() > expectedDepth)
            m_inLink = false;
        Q_ASSERT(m_inlinePath.size() == expectedDepth);
        m_inlinePath.resize(expectedDepth);
        m_inlineBaseDepths.removeLast();
        m_blockPath.removeLast();
    }
}
 
/*!
    Adds \a inline_ to the current block's inline content.
 
    If there is an active inline container (from FormattingLeft or
    Link atom), the inline is added to that container's children
    instead.
 
    If no block is open, the inline is dropped. This shouldn't happen
    with well-formed atom chains (text is always wrapped in
    ParaLeft/ParaRight), and is asserted in debug builds.
*/
void ContentBuilder::addInline(InlineContent inline_)
{
    if (!m_inlinePath.isEmpty()) {
        resolveInline()->children.append(std::move(inline_));
    } else if (!m_blockPath.isEmpty()) {
        resolveBlock()->inlineContent.append(std::move(inline_));
    } else {
        // Inline content without an enclosing block is dropped.
        // QDoc's atom chains always wrap text in ParaLeft/ParaRight,
        // so this path indicates a malformed chain.
        Q_ASSERT_X(false, "ContentBuilder::addInline",
                    "Inline content without an enclosing block");
    }
}
 
/*!
    Convenience method: creates a leaf InlineContent of the given
    \a type with \a text and appends it via addInline().
*/
void ContentBuilder::addLeafInline(InlineType type, const QString &text)
{
    InlineContent ic;
    ic.type = type;
    ic.text = text;
    addInline(std::move(ic));
}
 
/*!
    Pushes \a container as a new inline container. Subsequent
    addInline() and pushInlineContainer() calls will nest
    their content inside this container.
 
    Unlike addInline(), which only appends leaf inlines, this method
    also updates m_inlinePath to enable nesting. It respects the
    existing inline path: if we are already inside a Link or formatting
    container, the new container is added as a child of that container.
*/
void ContentBuilder::pushInlineContainer(InlineContent container)
{
    if (!m_inlinePath.isEmpty()) {
        auto *parent = resolveInline();
        parent->children.append(std::move(container));
        m_inlinePath.append(parent->children.size() - 1);
    } else if (!m_blockPath.isEmpty()) {
        auto *block = resolveBlock();
        block->inlineContent.append(std::move(container));
        m_inlinePath.append(block->inlineContent.size() - 1);
    }
}
 
/*!
    Resolves the current block path to a ContentBlock pointer.
 
    The returned pointer is valid only until the next QList mutation
    on any list in the path. Callers must use the pointer within a
    single expression and discard it before appending to any QList.
*/
ContentBlock *ContentBuilder::resolveBlock()
{
    Q_ASSERT(!m_blockPath.isEmpty());
    Q_ASSERT(m_blockPath[0] >= 0 && m_blockPath[0] < m_result.size());
    ContentBlock *block = &m_result[m_blockPath[0]];
    for (qsizetype i = 1; i < m_blockPath.size(); ++i) {
        Q_ASSERT(m_blockPath[i] >= 0 && m_blockPath[i] < block->children.size());
        block = &block->children[m_blockPath[i]];
    }
    return block;
}
 
/*!
    Resolves the current inline path to an InlineContent pointer.
 
    Walks the block path first (via resolveBlock()), then descends
    through the block's inlineContent and nested children lists
    using the indices in m_inlinePath.
*/
InlineContent *ContentBuilder::resolveInline()
{
    ContentBlock *block = resolveBlock();
    Q_ASSERT(!m_inlinePath.isEmpty());
    Q_ASSERT(m_inlinePath[0] >= 0 && m_inlinePath[0] < block->inlineContent.size());
    InlineContent *ic = &block->inlineContent[m_inlinePath[0]];
    for (qsizetype i = 1; i < m_inlinePath.size(); ++i) {
        Q_ASSERT(m_inlinePath[i] >= 0 && m_inlinePath[i] < ic->children.size());
        ic = &ic->children[m_inlinePath[i]];
    }
    return ic;
}
 
} // namespace IR
 
QT_END_NAMESPACE