member.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 "member.h"
 
#include "classificationjson.h"
 
#include <QJsonArray>
 
QT_BEGIN_NAMESPACE
 
using namespace Qt::Literals::StringLiterals;
 
namespace IR {
 
/*!
    \struct IR::ParameterIR
    \brief Intermediate representation of a function parameter.
 
    ParameterIR captures the type, name, and optional default value
    of a single function parameter. Templates use this to render
    parameter lists in function synopses.
 
    JSON output omits \c defaultValue when the string is empty,
    following the convention of suppressing absent optional fields.
*/
 
/*!
    \variable IR::ParameterIR::type
    Parameter type (such as "const QString &").
*/
 
/*!
    \variable IR::ParameterIR::name
    Parameter name.
*/
 
/*!
    \variable IR::ParameterIR::defaultValue
    Default value expression, empty if none.
*/
 
/*!
    Converts the parameter to a QJsonObject for template rendering.
 
    Always emits \c type and \c name. The \c defaultValue key is
    omitted when the default value string is empty.
*/
QJsonObject ParameterIR::toJson() const
{
    QJsonObject json;
    json["type"_L1] = type;
    json["name"_L1] = name;
    if (!defaultValue.isEmpty())
        json["defaultValue"_L1] = defaultValue;
    return json;
}
 
/*!
    \struct IR::EnumValueIR
    \brief Intermediate representation of a single enum value.
 
    EnumValueIR captures the name, explicit initializer, and version
    information for one enumerator. Templates use this to render
    enum value tables in class documentation.
 
    JSON output omits \c value and \c since when their respective
    strings are empty.
*/
 
/*!
    \variable IR::EnumValueIR::name
    Enumerator name.
*/
 
/*!
    \variable IR::EnumValueIR::value
    Explicit initializer expression, empty if the compiler assigns
    the value.
*/
 
/*!
    \variable IR::EnumValueIR::since
    Qt version that introduced this enumerator, empty if unversioned.
*/
 
/*!
    Converts the enum value to a QJsonObject for template rendering.
 
    Always emits \c name. The \c value and \c since keys are omitted
    when their respective strings are empty.
*/
QJsonObject EnumValueIR::toJson() const
{
    QJsonObject json;
    json["name"_L1] = name;
    if (!value.isEmpty())
        json["value"_L1] = value;
    if (!since.isEmpty())
        json["since"_L1] = since;
    return json;
}
 
/*!
    \struct IR::SharedDetailGroup
    \brief One documentation body and see-also list shared by a group of members.
 
    SharedDetailGroup captures the detail content that a group of members
    documented by a single shared comment (a SharedCommentNode) all share:
    one body and one see-also list, rendered once for the whole group.
 
    The group references its members positionally: \c firstIndex is the
    zero-based index of the group's first member in the section's member
    list, and \c count is the number of members it covers. Member identity,
    synopses, anchors, and per-member fields stay in the section's flat
    member list, which keeps ordinary member JSON unchanged; members of the
    group carry the group's index in their \c sharedGroup field instead of
    the shared body and see-also content.
 
    The lookup context the shared content was authored in (the
    SharedCommentNode) is deliberately not part of this IR; the extractor
    keeps it outside the template-facing representation.
 
    JSON output always emits \c firstIndex, \c count, \c body, and
    \c alsoList, the latter two even when empty, so that templates can
    index a group positionally and guard only on array length. The group's
    status sentence uses \c status and \c isPlural, with the noun and
    version fields emitted only when nonempty. The \c anchorId key is
    emitted only when nonempty; anonymous groups carry no key at all.
*/
 
/*!
    \variable IR::SharedDetailGroup::firstIndex
    Zero-based index of the group's first member in the section's member
    list. Negative when the group is not populated.
*/
 
/*!
    \variable IR::SharedDetailGroup::count
    Number of section members the group covers.
*/
 
/*!
    \variable IR::SharedDetailGroup::status
    The status of the shared comment, rather than any individual child.
*/
 
/*!
    \variable IR::SharedDetailGroup::isPlural
    Whether the group describes multiple members. Named property groups
    describe one entity and remain singular.
*/
 
/*!
    \variable IR::SharedDetailGroup::anchorId
    The page fragment the group itself is reachable at, such as
    \c font-prop for a named QML property group. Empty when the group
    has no anchor of its own (an anonymous shared comment) or when the
    fragment is already owned by another destination on the page. The
    group's children keep their own \c anchorId values.
*/
 
/*!
    \variable IR::SharedDetailGroup::deprecatedSince
    The plain version used in a scheduled-deprecation sentence.
*/
 
/*!
    \variable IR::SharedDetailGroup::typeNoun
    The singular or plural type noun used in the group's status sentence.
*/
 
/*!
    \variable IR::SharedDetailGroup::deprecatedSinceQualified
    The deprecation version, prefixed with the logical module name for QML.
*/
 
/*!
    \variable IR::SharedDetailGroup::body
    The documentation body authored on the shared comment.
*/
 
/*!
    \variable IR::SharedDetailGroup::alsoList
    The see-also list authored on the shared comment.
*/
 
/*!
    Converts the shared detail group to a QJsonObject for template rendering.
 
    Always emits \c firstIndex and \c count, and both the \c body and
    \c alsoList arrays, which may be empty. The \c anchorId key is
    omitted when empty.
*/
QJsonObject SharedDetailGroup::toJson() const
{
    QJsonObject json;
    json["firstIndex"_L1] = firstIndex;
    json["count"_L1] = count;
    json["status"_L1] = statusToJson(status);
    json["isPlural"_L1] = isPlural;
    if (!anchorId.isEmpty())
        json["anchorId"_L1] = anchorId;
    if (!deprecatedSince.isEmpty())
        json["deprecatedSince"_L1] = deprecatedSince;
    if (!typeNoun.isEmpty())
        json["typeNoun"_L1] = typeNoun;
    if (!deprecatedSinceQualified.isEmpty())
        json["deprecatedSinceQualified"_L1] = deprecatedSinceQualified;
 
    QJsonArray bodyArray;
    for (const auto &block : body)
        bodyArray.append(block.toJson());
    json["body"_L1] = bodyArray;
 
    QJsonArray alsoArray;
    for (const auto &block : alsoList)
        alsoArray.append(block.toJson());
    json["alsoList"_L1] = alsoArray;
 
    return json;
}
 
/*!
    \struct IR::MemberIR
    \brief Intermediate representation of a single documentable member.
 
    MemberIR captures identity, classification, and type-specific
    metadata for one member of an aggregate (such as a class,
    namespace, or QML type). Function members carry parameter lists
    and overload metadata; enum members carry value listings.
    Templates use this to render summary tables and detail sections.
 
    JSON output omits \c parameters and \c enumValues when the
    respective lists are empty. The \c nodeType field is omitted
    when set to NoType.
*/
 
/*!
    \variable IR::MemberIR::name
    Unqualified member name.
*/
 
/*!
    \variable IR::MemberIR::fullName
    Fully qualified name including the enclosing scope.
*/
 
/*!
    \variable IR::MemberIR::signature
    Display signature for synopsis rendering. The format depends on
    the member type: functions include return type and default values,
    properties use "name : type", and enums include the scoped or
    unscoped distinction.
*/
 
/*!
    \variable IR::MemberIR::href
    URL of the member's detailed documentation.
*/
 
/*!
    \variable IR::MemberIR::brief
    One-line summary extracted from the member's doc comment,
    empty if none.
*/
 
/*!
    \variable IR::MemberIR::nodeType
    Classification of the member's entity type (function, property,
    enum, and so on). Defaults to NoType.
*/
 
/*!
    \variable IR::MemberIR::access
    Access level (public, protected, or private). Defaults to Public.
*/
 
/*!
    \variable IR::MemberIR::status
    Documentation status (active, deprecated, preliminary, or
    internal). Defaults to Active.
*/
 
/*!
    \variable IR::MemberIR::deprecatedSince
    Version the member was deprecated in, or the version in which a
    scheduled deprecation takes place. Empty when no deprecation
    status sentence applies.
*/
 
/*!
    \variable IR::MemberIR::typeNoun
    Human-readable noun for the member's node type (such as
    "function", "property", or "method"), used to build the
    deprecation status sentence. Empty when no status sentence
    applies.
*/
 
/*!
    \variable IR::MemberIR::deprecatedSinceQualified
    The deprecation version prefixed with the QML module name for QML
    members that have a logical module name (such as "QtQuick 6.5");
    otherwise the plain \c deprecatedSince. Empty when no status
    sentence applies or when there is no version.
*/
 
/*!
    \variable IR::MemberIR::parameters
    Parameter list for function members. Empty for non-functions.
*/
 
/*!
    \variable IR::MemberIR::overloadNumber
    Zero-based overload index. Zero indicates the primary overload.
*/
 
/*!
    \variable IR::MemberIR::isPrimaryOverload
    Whether this is the primary (first) overload of its name.
    Defaults to true.
*/
 
/*!
    \variable IR::MemberIR::enumValues
    Value list for enum members. Empty for non-enums.
*/
 
/*!
    \variable IR::MemberIR::signatureSpans
    Structured signature spans carrying semantic roles and resolved
    hrefs. When populated, templates can render rich signatures with
    type links and role-based styling. Empty by default for backward
    compatibility with the plain text \c synopsis field.
*/
 
/*!
    \variable IR::MemberIR::isStatic
    Whether the member is declared static.
*/
 
/*!
    \variable IR::MemberIR::isConst
    Whether the member is declared const.
*/
 
/*!
    \variable IR::MemberIR::isVirtual
    Whether the member is virtual (including pure virtual and
    override).
*/
 
/*!
    \variable IR::MemberIR::isSignal
    Whether the member is a Qt signal.
*/
 
/*!
    \variable IR::MemberIR::isSlot
    Whether the member is a Qt slot.
*/
 
/*!
    \variable IR::MemberIR::sharedGroup
    Index of the section's shared detail group this member belongs to, or
    -1 when the member carries its own body and see-also content. A member
    of a shared group has an empty \c body and \c alsoList; the shared
    content is rendered once from the group its index refers to. The
    \c sharedGroup key is omitted from JSON when -1.
*/
 
/*!
    Converts the member to a QJsonObject for template rendering.
 
    Emits identity fields (name, fullName, signature, href),
    classification as \c {id, label} objects, overload metadata, and
    qualifier flags. The \c brief, \c parameters, and \c enumValues
    fields are omitted when empty. The \c nodeType field is omitted
    when NoType. The \c sharedGroup field is omitted when -1.
*/
QJsonObject MemberIR::toJson() const
{
    QJsonObject json;
 
    json["name"_L1] = name;
    json["fullName"_L1] = fullName;
    json["signature"_L1] = signature;
    json["href"_L1] = href;
    if (!brief.isEmpty())
        json["brief"_L1] = brief;
 
    if (const auto t = nodeTypeToJson(nodeType))
        json["nodeType"_L1] = *t;
    json["status"_L1] = statusToJson(status);
    json["access"_L1] = accessToJson(access);
    if (!deprecatedSince.isEmpty())
        json["deprecatedSince"_L1] = deprecatedSince;
    if (!typeNoun.isEmpty())
        json["typeNoun"_L1] = typeNoun;
    if (!deprecatedSinceQualified.isEmpty())
        json["deprecatedSinceQualified"_L1] = deprecatedSinceQualified;
 
    json["overloadNumber"_L1] = overloadNumber;
    json["isPrimaryOverload"_L1] = isPrimaryOverload;
 
    if (!parameters.isEmpty()) {
        QJsonArray arr;
        for (const auto &p : parameters)
            arr.append(p.toJson());
        json["parameters"_L1] = arr;
    }
 
    if (!enumValues.isEmpty()) {
        QJsonArray arr;
        for (const auto &ev : enumValues)
            arr.append(ev.toJson());
        json["enumValues"_L1] = arr;
    }
 
    json["isStatic"_L1] = isStatic;
    json["isConst"_L1] = isConst;
    json["isVirtual"_L1] = isVirtual;
    json["isSignal"_L1] = isSignal;
    json["isSlot"_L1] = isSlot;
 
    if (isAttached)
        json["isAttached"_L1] = true;
    if (isDefault)
        json["isDefault"_L1] = true;
    if (isReadOnly)
        json["isReadOnly"_L1] = true;
    if (isRequired)
        json["isRequired"_L1] = true;
    if (!dataType.isEmpty())
        json["dataType"_L1] = dataType;
 
    json["anchorId"_L1] = anchorId;
    json["synopsis"_L1] = synopsis;
    if (!signatureSpans.isEmpty()) {
        QJsonArray arr;
        for (const auto &span : signatureSpans)
            arr.append(span.toJson());
        json["signatureSpans"_L1] = arr;
    }
    if (!since.isEmpty())
        json["since"_L1] = since;
    if (!threadSafety.isEmpty())
        json["threadSafety"_L1] = threadSafety;
    if (!comparisonCategory.isEmpty())
        json["comparisonCategory"_L1] = comparisonCategory;
    if (isNoexcept)
        json["isNoexcept"_L1] = true;
    if (!noexceptNote.isEmpty())
        json["noexceptNote"_L1] = noexceptNote;
 
    if (!body.isEmpty()) {
        QJsonArray arr;
        for (const auto &block : body)
            arr.append(block.toJson());
        json["body"_L1] = arr;
    }
 
    if (!alsoList.isEmpty()) {
        QJsonArray arr;
        for (const auto &block : alsoList)
            arr.append(block.toJson());
        json["alsoList"_L1] = arr;
    }
 
    if (sharedGroup >= 0)
        json["sharedGroup"_L1] = sharedGroup;
 
    return json;
}
 
/*!
    \struct IR::InheritedMembersIR
    \brief Summary of members inherited from a single base class.
 
    InheritedMembersIR stores a count and link target for one base
    class's contributed members. Templates use this to render lines
    such as "5 public functions inherited from QObject" at the end
    of a section.
*/
 
/*!
    \variable IR::InheritedMembersIR::className
    Fully qualified name of the base class.
*/
 
/*!
    \variable IR::InheritedMembersIR::count
    Number of members inherited from this base class.
*/
 
/*!
    \variable IR::InheritedMembersIR::href
    URL of the base class's documentation page.
*/
 
/*!
    Converts the inherited members summary to a QJsonObject.
 
    Emits \c className, \c count, and \c href. Templates combine
    this with the enclosing section's \c plural field to render
    links such as "5 public functions inherited from QObject".
*/
QJsonObject InheritedMembersIR::toJson() const
{
    QJsonObject json;
    json["className"_L1] = className;
    json["count"_L1] = count;
    json["href"_L1] = href;
    return json;
}
 
/*!
    \struct IR::SectionIR
    \brief Intermediate representation of a member summary section.
 
    SectionIR groups members by category (such as "Public Functions"
    or "Properties") for summary table rendering. Each section carries
    a title, singular and plural forms for inherited-member links, and
    three member lists: primary members, reimplemented members, and
    inherited member summaries.
 
    The \c sharedGroups list carries the shared detail content of
    member groups documented by a single shared comment; each group's
    members stay in the flat \c members list and reference their group
    through \c sharedGroup. The \c reimplementedMembers,
    \c inheritedMembers, and \c sharedGroups arrays are omitted from
    JSON when empty.
*/
 
/*!
    \variable IR::SectionIR::id
    Stable ASCII identifier for anchor links, generated from the
    title via TextUtils::asAsciiPrintable().
*/
 
/*!
    \variable IR::SectionIR::title
    Display title (such as "Public Functions" or "Properties").
*/
 
/*!
    \variable IR::SectionIR::singular
    Singular form of the member type (such as "function").
*/
 
/*!
    \variable IR::SectionIR::plural
    Plural form of the member type (such as "functions").
*/
 
/*!
    \variable IR::SectionIR::members
    Primary members in this section.
*/
 
/*!
    \variable IR::SectionIR::reimplementedMembers
    Members that reimplement a virtual function from a base class.
*/
 
/*!
    \variable IR::SectionIR::inheritedMembers
    Summaries of members inherited from base classes.
*/
 
/*!
    \variable IR::SectionIR::sharedGroups
    Shared detail groups whose members appear in this section's
    \c members list, in the order the groups are encountered. Empty
    (and omitted from JSON) when the section has no shared comment
    groups.
*/
 
/*!
    Converts the section to a QJsonObject for template rendering.
 
    Emits \c id, \c title, \c singular, \c plural, and the \c members
    array. The \c reimplementedMembers, \c inheritedMembers, and
    \c sharedGroups arrays are omitted when empty.
*/
QJsonObject SectionIR::toJson() const
{
    QJsonObject json;
 
    json["id"_L1] = id;
    json["title"_L1] = title;
    json["singular"_L1] = singular;
    json["plural"_L1] = plural;
 
    QJsonArray membersArray;
    for (const auto &m : members)
        membersArray.append(m.toJson());
    json["members"_L1] = membersArray;
 
    if (!reimplementedMembers.isEmpty()) {
        QJsonArray arr;
        for (const auto &m : reimplementedMembers)
            arr.append(m.toJson());
        json["reimplementedMembers"_L1] = arr;
    }
 
    if (!inheritedMembers.isEmpty()) {
        QJsonArray arr;
        for (const auto &im : inheritedMembers)
            arr.append(im.toJson());
        json["inheritedMembers"_L1] = arr;
    }
 
    if (!sharedGroups.isEmpty()) {
        QJsonArray arr;
        for (const auto &group : sharedGroups)
            arr.append(group.toJson());
        json["sharedGroups"_L1] = arr;
    }
 
    return json;
}
 
/*!
    \struct IR::AllMemberEntry
    \brief A single entry in an all-members listing page.
 
    AllMemberEntry captures the display signature and link target for
    one member on an all-members sub-page. QML properties carry display
    hints (such as "read-only" or "default") and property groups nest
    child entries under a parent.
*/
 
/*!
    Converts the entry to a QJsonObject for template rendering.
 
    Always emits \c signature and \c href. The \c hints array, \c
    isPropertyGroup flag, and \c children array are omitted when
    empty or false.
*/
QJsonObject AllMemberEntry::toJson() const
{
    QJsonObject json;
    json["signature"_L1] = signature;
    if (!signatureSpans.isEmpty()) {
        QJsonArray arr;
        for (const auto &span : signatureSpans)
            arr.append(span.toJson());
        json["signatureSpans"_L1] = arr;
    }
    json["href"_L1] = href;
 
    if (!hints.isEmpty()) {
        QJsonArray arr;
        for (const auto &hint : hints)
            arr.append(hint);
        json["hints"_L1] = arr;
    }
 
    if (isPropertyGroup)
        json["isPropertyGroup"_L1] = true;
 
    if (!children.isEmpty()) {
        QJsonArray arr;
        for (const auto &child : children)
            arr.append(child.toJson());
        json["children"_L1] = arr;
    }
 
    return json;
}
 
/*!
    \struct IR::MemberGroup
    \brief Members grouped by originating QML type in an all-members listing.
 
    MemberGroup groups AllMemberEntry items by the QML type they originate
    from, enabling templates to render "inherited from ..." headings. An
    empty \c typeName indicates the type's own members.
*/
 
/*!
    Converts the member group to a QJsonObject for template rendering.
 
    Always emits \c typeName (even when empty, since empty means own
    members), \c typeHref, and \c members array.
*/
QJsonObject MemberGroup::toJson() const
{
    QJsonObject json;
    json["typeName"_L1] = typeName;
    json["typeHref"_L1] = typeHref;
 
    QJsonArray arr;
    for (const auto &entry : members)
        arr.append(entry.toJson());
    json["members"_L1] = arr;
 
    return json;
}
 
/*!
    \struct IR::AllMembersIR
    \brief Intermediate representation of the all-members listing page.
 
    AllMembersIR captures all data needed to render a member listing
    sub-page. It supports two rendering paths: a flat alphabetical list
    for C++ classes and a grouped-by-origin-type list for QML types.
    The \c isQmlType flag determines which path the template uses.
*/
 
/*!
    Converts the all-members IR to a QJsonObject for template rendering.
 
    Always emits \c typeName, \c typeHref, and \c isQmlType. The
    \c members and \c memberGroups arrays are emitted only when
    non-empty, letting templates distinguish C++ from QML by checking
    which key exists.
*/
QJsonObject AllMembersIR::toJson() const
{
    QJsonObject json;
    json["typeName"_L1] = typeName;
    json["typeHref"_L1] = typeHref;
    json["isQmlType"_L1] = isQmlType;
 
    if (!members.isEmpty()) {
        QJsonArray arr;
        for (const auto &entry : members)
            arr.append(entry.toJson());
        json["members"_L1] = arr;
    }
 
    if (!memberGroups.isEmpty()) {
        QJsonArray arr;
        for (const auto &group : memberGroups)
            arr.append(group.toJson());
        json["memberGroups"_L1] = arr;
    }
 
    return json;
}
 
} // namespace IR
 
QT_END_NAMESPACE