qdocdatabase.cpp

Go to the documentation of this file.

// Copyright (C) 2021 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GPL-3.0-only WITH Qt-GPL-exception-1.0
 
#include "qdocdatabase.h"
 
#include "atom.h"
#include "collectionnode.h"
#include "functionnode.h"
#include "generator.h"
#include "qdocindexfiles.h"
#include "tree.h"
 
#include <QtCore/qregularexpression.h>
#include <stack>
 
QT_BEGIN_NAMESPACE
 
using namespace Qt::StringLiterals;
static NodeMultiMap emptyNodeMultiMap_;
 
/*!
  \class QDocForest
 
  A class representing a forest of Tree objects.
 
  This private class manages a collection of Tree objects (a
  forest) for the singleton QDocDatabase object. It is only
  accessed by that singleton QDocDatabase object, which is a
  friend. Each tree in the forest is an instance of class
  Tree, which is a mostly private class. Both QDocForest and
  QDocDatabase are friends of Tree and have full access.
 
  There are two kinds of trees in the forest, differing not
  in structure but in use. One Tree is the primary tree. It
  is the tree representing the module being documented. All
  the other trees in the forest are called index trees. Each
  one represents the contents of the index file for one of
  the modules the current module must be able to link to.
 
  The instances of subclasses of Node in the primary tree
  will contain documentation in an instance of Doc. The
  index trees contain no documentation, and each Node in
  an index tree is marked as an index node.
 
  Each tree is named with the name of its module.
 
  The search order is created by searchOrder(), if it has
  not already been created. The search order and module
  names arrays have parallel structure, i.e. modulNames_[i]
  is the module name of the Tree at searchOrder_[i].
 
  The primary tree is always the first tree in the search
  order. i.e., when the database is searched, the primary
  tree is always searched first, unless a specific tree is
  being searched.
 */
 
/*!
  Destroys the qdoc forest. This requires deleting
  each Tree in the forest. Note that the forest has
  been transferred into the search order array, so
  what is really being used to destroy the forest
  is the search order array.
 */
QDocForest::~QDocForest()
{
    for (auto *entry : m_searchOrder)
        delete entry;
    m_forest.clear();
    m_searchOrder.clear();
    m_indexSearchOrder.clear();
    m_moduleNames.clear();
    m_primaryTree = nullptr;
}
 
/*!
  Initializes the forest prior to a traversal and
  returns a pointer to the primary tree. If the
  forest is empty, it returns \nullptr.
 */
Tree *QDocForest::firstTree()
{
    m_currentIndex = 0;
    return (!searchOrder().isEmpty() ? searchOrder()[0] : nullptr);
}
 
/*!
  Increments the forest's current tree index. If the current
  tree index is still within the forest, the function returns
  the pointer to the current tree. Otherwise it returns \nullptr.
 */
Tree *QDocForest::nextTree()
{
    ++m_currentIndex;
    return (m_currentIndex < searchOrder().size() ? searchOrder()[m_currentIndex] : nullptr);
}
 
/*!
  \fn Tree *QDocForest::primaryTree()
 
  Returns the pointer to the primary tree.
 */
 
/*!
  Finds the tree for module \a t in the forest and
  sets the primary tree to be that tree. After the
  primary tree is set, that tree is removed from the
  forest.
 
  \node It gets re-inserted into the forest after the
  search order is built.
 */
void QDocForest::setPrimaryTree(const QString &t)
{
    QString T = t.toLower();
    m_primaryTree = findTree(T);
    m_forest.remove(T);
    if (m_primaryTree == nullptr)
        qCCritical(lcQdoc) << "Error: Could not set primary tree to" << t;
}
 
/*!
  If the search order array is empty, create the search order.
  If the search order array is not empty, do nothing.
 */
void QDocForest::setSearchOrder(const QStringList &t)
{
    if (!m_searchOrder.isEmpty())
        return;
 
    /* Allocate space for the search order. */
    m_searchOrder.reserve(m_forest.size() + 1);
    m_searchOrder.clear();
    m_moduleNames.reserve(m_forest.size() + 1);
    m_moduleNames.clear();
 
    /* The primary tree is always first in the search order. */
    QString primaryName = primaryTree()->physicalModuleName();
    m_searchOrder.append(m_primaryTree);
    m_moduleNames.append(primaryName);
    m_forest.remove(primaryName);
 
    for (const QString &m : t) {
        if (primaryName != m) {
            auto it = m_forest.find(m);
            if (it != m_forest.end()) {
                m_searchOrder.append(it.value());
                m_moduleNames.append(m);
                m_forest.remove(m);
            }
        }
    }
    /*
      If any trees remain in the forest, just add them
      to the search order sequentially, because we don't
      know any better at this point.
     */
    if (!m_forest.isEmpty()) {
        for (auto it = m_forest.begin(); it != m_forest.end(); ++it) {
            m_searchOrder.append(it.value());
            m_moduleNames.append(it.key());
        }
        m_forest.clear();
    }
 
    /*
      Rebuild the forest after constructing the search order.
      It was destroyed during construction of the search order,
      but it is needed for module-specific searches.
 
      Note that this loop also inserts the primary tree into the
      forrest. That is a requirement.
     */
    for (int i = 0; i < m_searchOrder.size(); ++i) {
        if (!m_forest.contains(m_moduleNames.at(i))) {
            m_forest.insert(m_moduleNames.at(i), m_searchOrder.at(i));
        }
    }
}
 
/*!
  Returns an ordered array of Tree pointers that represents
  the order in which the trees should be searched. The first
  Tree in the array is the tree for the current module, i.e.
  the module for which qdoc is generating documentation.
 
  The other Tree pointers in the array represent the index
  files that were loaded in preparation for generating this
  module's documentation. Each Tree pointer represents one
  index file. The index file Tree points have been ordered
  heuristically to, hopefully, minimize searching. Thr order
  will probably be changed.
 
  If the search order array is empty, this function calls
  indexSearchOrder(). The search order array is empty while
  the index files are being loaded, but some searches must
  be performed during this time, notably searches for base
  class nodes. These searches require a temporary search
  order. The temporary order changes throughout the loading
  of the index files, but it is always the tree for the
  current index file first, followed by the trees for the
  index files that have already been loaded. The only
  ordering required in this temporary search order is that
  the current tree must be searched first.
 */
const QList<Tree *> &QDocForest::searchOrder()
{
    if (m_searchOrder.isEmpty())
        return indexSearchOrder();
    return m_searchOrder;
}
 
/*!
  There are two search orders used by qdoc when searching for
  things. The normal search order is returned by searchOrder(),
  but this normal search order is not known until all the index
  files have been read. At that point, setSearchOrder() is
  called.
 
  During the reading of the index files, the vector holding
  the normal search order remains empty. Whenever the search
  order is requested, if that vector is empty, this function
  is called to return a temporary search order, which includes
  all the index files that have been read so far, plus the
  one being read now. That one is prepended to the front of
  the vector.
 */
const QList<Tree *> &QDocForest::indexSearchOrder()
{
    if (m_forest.size() > m_indexSearchOrder.size())
        m_indexSearchOrder.prepend(m_primaryTree);
    return m_indexSearchOrder;
}
 
/*!
  Create a new Tree for the index file for the specified
  \a module and add it to the forest. Return the pointer
  to its root.
 */
NamespaceNode *QDocForest::newIndexTree(const QString &module)
{
    m_primaryTree = new Tree(module, m_qdb);
    m_forest.insert(module.toLower(), m_primaryTree);
    return m_primaryTree->root();
}
 
/*!
  Create a new Tree for use as the primary tree. This tree
  will represent the primary module. \a module is camel case.
 */
void QDocForest::newPrimaryTree(const QString &module)
{
    m_primaryTree = new Tree(module, m_qdb);
}
 
/*!
  Searches through the forest for a node named \a targetPath
  and returns a pointer to it if found. The \a relative node
  is the starting point. It only makes sense for the primary
  tree, which is searched first. After the primary tree has
  been searched, \a relative is set to 0 for searching the
  other trees, which are all index trees. With relative set
  to 0, the starting point for each index tree is the root
  of the index tree.
 
  If \a targetPath is resolved successfully but it refers to
  a \\section title, continue the search, keeping the section
  title as a fallback if no higher-priority targets are found.
 */
const Node *QDocForest::findNodeForTarget(QStringList &targetPath, const Node *relative,
                                          Node::Genus genus, QString &ref)
{
    int flags = SearchBaseClasses | SearchEnumValues;
 
    QString entity = targetPath.takeFirst();
    QStringList entityPath = entity.split("::");
 
    QString target;
    if (!targetPath.isEmpty())
        target = targetPath.takeFirst();
 
    TargetRec::TargetType type = TargetRec::Unknown;
    const Node *tocNode = nullptr;
    for (const auto *tree : searchOrder()) {
        const Node *n = tree->findNodeForTarget(entityPath, target, relative, flags, genus, ref, &type);
        if (n) {
            // Targets referring to non-section titles are returned immediately
            if (type != TargetRec::Contents)
                return n;
            if (!tocNode)
                tocNode = n;
        }
        relative = nullptr;
    }
    return tocNode;
}
 
/*!
  Finds the FunctionNode for the qualified function name
  in \a path, that also has the specified \a parameters.
  Returns a pointer to the first matching function.
 
  \a relative is a node in the primary tree where the search
  should begin. It is only used when searching the primary
  tree. \a genus can be used to force the search to find a
  C++ function or a QML function.
 */
const FunctionNode *QDocForest::findFunctionNode(const QStringList &path,
                                                 const Parameters &parameters, const Node *relative,
                                                 Node::Genus genus)
{
    for (const auto *tree : searchOrder()) {
        const FunctionNode *fn = tree->findFunctionNode(path, parameters, relative, genus);
        if (fn)
            return fn;
        relative = nullptr;
    }
    return nullptr;
}
 
/*! \class QDocDatabase
  This class provides exclusive access to the qdoc database,
  which consists of a forrest of trees and a lot of maps and
  other useful data structures.
 */
 
QDocDatabase *QDocDatabase::s_qdocDB = nullptr;
NodeMap QDocDatabase::s_typeNodeMap;
NodeMultiMap QDocDatabase::s_obsoleteClasses;
NodeMultiMap QDocDatabase::s_classesWithObsoleteMembers;
NodeMultiMap QDocDatabase::s_obsoleteQmlTypes;
NodeMultiMap QDocDatabase::s_qmlTypesWithObsoleteMembers;
NodeMultiMap QDocDatabase::s_cppClasses;
NodeMultiMap QDocDatabase::s_qmlBasicTypes;
NodeMultiMap QDocDatabase::s_qmlTypes;
NodeMultiMap QDocDatabase::s_examples;
NodeMultiMapMap QDocDatabase::s_newClassMaps;
NodeMultiMapMap QDocDatabase::s_newQmlTypeMaps;
NodeMultiMapMap QDocDatabase::s_newEnumValueMaps;
NodeMultiMapMap QDocDatabase::s_newSinceMaps;
 
/*!
  Constructs the singleton qdoc database object. The singleton
  constructs the \a forest_ object, which is also a singleton.
  \a m_showInternal is normally false. If it is true, qdoc will
  write documentation for nodes marked \c internal.
 
  \a singleExec_ is false when qdoc is being used in the standard
  way of running qdoc twices for each module, first with -prepare
  and then with -generate. First the -prepare phase is run for
  each module, then the -generate phase is run for each module.
 
  When \a singleExec_ is true, qdoc is run only once. During the
  single execution, qdoc processes the qdocconf files for all the
  modules sequentially in a loop. Each source file for each module
  is read exactly once.
 */
QDocDatabase::QDocDatabase() : m_forest(this)
{
    // nothing
}
 
/*!
  Creates the singleton. Allows only one instance of the class
  to be created. Returns a pointer to the singleton.
*/
QDocDatabase *QDocDatabase::qdocDB()
{
    if (s_qdocDB == nullptr) {
        s_qdocDB = new QDocDatabase;
        initializeDB();
    }
    return s_qdocDB;
}
 
/*!
  Destroys the singleton.
 */
void QDocDatabase::destroyQdocDB()
{
    if (s_qdocDB != nullptr) {
        delete s_qdocDB;
        s_qdocDB = nullptr;
    }
}
 
/*!
  Initialize data structures in the singleton qdoc database.
 
  In particular, the type node map is initialized with a lot
  type names that don't refer to documented types. For example,
  many C++ standard types are included. These might be documented
  here at some point, but for now they are not. Other examples
  include \c array and \c data, which are just generic names
  used as place holders in function signatures that appear in
  the documentation.
 
  \note Do not add QML basic types into this list as it will
        break linking to those types.
 */
void QDocDatabase::initializeDB()
{
    s_typeNodeMap.insert("accepted", nullptr);
    s_typeNodeMap.insert("actionPerformed", nullptr);
    s_typeNodeMap.insert("activated", nullptr);
    s_typeNodeMap.insert("alias", nullptr);
    s_typeNodeMap.insert("anchors", nullptr);
    s_typeNodeMap.insert("any", nullptr);
    s_typeNodeMap.insert("array", nullptr);
    s_typeNodeMap.insert("autoSearch", nullptr);
    s_typeNodeMap.insert("axis", nullptr);
    s_typeNodeMap.insert("backClicked", nullptr);
    s_typeNodeMap.insert("boomTime", nullptr);
    s_typeNodeMap.insert("border", nullptr);
    s_typeNodeMap.insert("buttonClicked", nullptr);
    s_typeNodeMap.insert("callback", nullptr);
    s_typeNodeMap.insert("char", nullptr);
    s_typeNodeMap.insert("clicked", nullptr);
    s_typeNodeMap.insert("close", nullptr);
    s_typeNodeMap.insert("closed", nullptr);
    s_typeNodeMap.insert("cond", nullptr);
    s_typeNodeMap.insert("data", nullptr);
    s_typeNodeMap.insert("dataReady", nullptr);
    s_typeNodeMap.insert("dateString", nullptr);
    s_typeNodeMap.insert("dateTimeString", nullptr);
    s_typeNodeMap.insert("datetime", nullptr);
    s_typeNodeMap.insert("day", nullptr);
    s_typeNodeMap.insert("deactivated", nullptr);
    s_typeNodeMap.insert("drag", nullptr);
    s_typeNodeMap.insert("easing", nullptr);
    s_typeNodeMap.insert("error", nullptr);
    s_typeNodeMap.insert("exposure", nullptr);
    s_typeNodeMap.insert("fatalError", nullptr);
    s_typeNodeMap.insert("fileSelected", nullptr);
    s_typeNodeMap.insert("flags", nullptr);
    s_typeNodeMap.insert("float", nullptr);
    s_typeNodeMap.insert("focus", nullptr);
    s_typeNodeMap.insert("focusZone", nullptr);
    s_typeNodeMap.insert("format", nullptr);
    s_typeNodeMap.insert("framePainted", nullptr);
    s_typeNodeMap.insert("from", nullptr);
    s_typeNodeMap.insert("frontClicked", nullptr);
    s_typeNodeMap.insert("function", nullptr);
    s_typeNodeMap.insert("hasOpened", nullptr);
    s_typeNodeMap.insert("hovered", nullptr);
    s_typeNodeMap.insert("hoveredTitle", nullptr);
    s_typeNodeMap.insert("hoveredUrl", nullptr);
    s_typeNodeMap.insert("imageCapture", nullptr);
    s_typeNodeMap.insert("imageProcessing", nullptr);
    s_typeNodeMap.insert("index", nullptr);
    s_typeNodeMap.insert("initialized", nullptr);
    s_typeNodeMap.insert("isLoaded", nullptr);
    s_typeNodeMap.insert("item", nullptr);
    s_typeNodeMap.insert("key", nullptr);
    s_typeNodeMap.insert("keysequence", nullptr);
    s_typeNodeMap.insert("listViewClicked", nullptr);
    s_typeNodeMap.insert("loadRequest", nullptr);
    s_typeNodeMap.insert("locale", nullptr);
    s_typeNodeMap.insert("location", nullptr);
    s_typeNodeMap.insert("long", nullptr);
    s_typeNodeMap.insert("message", nullptr);
    s_typeNodeMap.insert("messageReceived", nullptr);
    s_typeNodeMap.insert("mode", nullptr);
    s_typeNodeMap.insert("month", nullptr);
    s_typeNodeMap.insert("name", nullptr);
    s_typeNodeMap.insert("number", nullptr);
    s_typeNodeMap.insert("object", nullptr);
    s_typeNodeMap.insert("offset", nullptr);
    s_typeNodeMap.insert("ok", nullptr);
    s_typeNodeMap.insert("openCamera", nullptr);
    s_typeNodeMap.insert("openImage", nullptr);
    s_typeNodeMap.insert("openVideo", nullptr);
    s_typeNodeMap.insert("padding", nullptr);
    s_typeNodeMap.insert("parent", nullptr);
    s_typeNodeMap.insert("path", nullptr);
    s_typeNodeMap.insert("photoModeSelected", nullptr);
    s_typeNodeMap.insert("position", nullptr);
    s_typeNodeMap.insert("precision", nullptr);
    s_typeNodeMap.insert("presetClicked", nullptr);
    s_typeNodeMap.insert("preview", nullptr);
    s_typeNodeMap.insert("previewSelected", nullptr);
    s_typeNodeMap.insert("progress", nullptr);
    s_typeNodeMap.insert("puzzleLost", nullptr);
    s_typeNodeMap.insert("qmlSignal", nullptr);
    s_typeNodeMap.insert("rectangle", nullptr);
    s_typeNodeMap.insert("request", nullptr);
    s_typeNodeMap.insert("requestId", nullptr);
    s_typeNodeMap.insert("section", nullptr);
    s_typeNodeMap.insert("selected", nullptr);
    s_typeNodeMap.insert("send", nullptr);
    s_typeNodeMap.insert("settingsClicked", nullptr);
    s_typeNodeMap.insert("shoe", nullptr);
    s_typeNodeMap.insert("short", nullptr);
    s_typeNodeMap.insert("signed", nullptr);
    s_typeNodeMap.insert("sizeChanged", nullptr);
    s_typeNodeMap.insert("size_t", nullptr);
    s_typeNodeMap.insert("sockaddr", nullptr);
    s_typeNodeMap.insert("someOtherSignal", nullptr);
    s_typeNodeMap.insert("sourceSize", nullptr);
    s_typeNodeMap.insert("startButtonClicked", nullptr);
    s_typeNodeMap.insert("state", nullptr);
    s_typeNodeMap.insert("std::initializer_list", nullptr);
    s_typeNodeMap.insert("std::list", nullptr);
    s_typeNodeMap.insert("std::map", nullptr);
    s_typeNodeMap.insert("std::pair", nullptr);
    s_typeNodeMap.insert("std::string", nullptr);
    s_typeNodeMap.insert("std::vector", nullptr);
    s_typeNodeMap.insert("stringlist", nullptr);
    s_typeNodeMap.insert("swapPlayers", nullptr);
    s_typeNodeMap.insert("symbol", nullptr);
    s_typeNodeMap.insert("t", nullptr);
    s_typeNodeMap.insert("T", nullptr);
    s_typeNodeMap.insert("tagChanged", nullptr);
    s_typeNodeMap.insert("timeString", nullptr);
    s_typeNodeMap.insert("timeout", nullptr);
    s_typeNodeMap.insert("to", nullptr);
    s_typeNodeMap.insert("toggled", nullptr);
    s_typeNodeMap.insert("type", nullptr);
    s_typeNodeMap.insert("unsigned", nullptr);
    s_typeNodeMap.insert("urllist", nullptr);
    s_typeNodeMap.insert("va_list", nullptr);
    s_typeNodeMap.insert("value", nullptr);
    s_typeNodeMap.insert("valueEmitted", nullptr);
    s_typeNodeMap.insert("videoFramePainted", nullptr);
    s_typeNodeMap.insert("videoModeSelected", nullptr);
    s_typeNodeMap.insert("videoRecorder", nullptr);
    s_typeNodeMap.insert("void", nullptr);
    s_typeNodeMap.insert("volatile", nullptr);
    s_typeNodeMap.insert("wchar_t", nullptr);
    s_typeNodeMap.insert("x", nullptr);
    s_typeNodeMap.insert("y", nullptr);
    s_typeNodeMap.insert("zoom", nullptr);
    s_typeNodeMap.insert("zoomTo", nullptr);
}
 
/*! \fn NamespaceNode *QDocDatabase::primaryTreeRoot()
  Returns a pointer to the root node of the primary tree.
 */
 
/*!
  \fn const CNMap &QDocDatabase::groups()
  Returns a const reference to the collection of all
  group nodes in the primary tree.
*/
 
/*!
  \fn const CNMap &QDocDatabase::modules()
  Returns a const reference to the collection of all
  module nodes in the primary tree.
*/
 
/*!
  \fn const CNMap &QDocDatabase::qmlModules()
  Returns a const reference to the collection of all
  QML module nodes in the primary tree.
*/
 
/*! \fn CollectionNode *QDocDatabase::findGroup(const QString &name)
  Find the group node named \a name and return a pointer
  to it. If a matching node is not found, add a new group
  node named \a name and return a pointer to that one.
 
  If a new group node is added, its parent is the tree root,
  and the new group node is marked \e{not seen}.
 */
 
/*! \fn CollectionNode *QDocDatabase::findModule(const QString &name)
  Find the module node named \a name and return a pointer
  to it. If a matching node is not found, add a new module
  node named \a name and return a pointer to that one.
 
  If a new module node is added, its parent is the tree root,
  and the new module node is marked \e{not seen}.
 */
 
/*! \fn CollectionNode *QDocDatabase::addGroup(const QString &name)
  Looks up the group named \a name in the primary tree. If
  a match is found, a pointer to the node is returned.
  Otherwise, a new group node named \a name is created and
  inserted into the collection, and the pointer to that node
  is returned.
 */
 
/*! \fn CollectionNode *QDocDatabase::addModule(const QString &name)
  Looks up the module named \a name in the primary tree. If
  a match is found, a pointer to the node is returned.
  Otherwise, a new module node named \a name is created and
  inserted into the collection, and the pointer to that node
  is returned.
 */
 
/*! \fn CollectionNode *QDocDatabase::addQmlModule(const QString &name)
  Looks up the QML module named \a name in the primary tree.
  If a match is found, a pointer to the node is returned.
  Otherwise, a new QML module node named \a name is created
  and inserted into the collection, and the pointer to that
  node is returned.
 */
 
/*! \fn CollectionNode *QDocDatabase::addToGroup(const QString &name, Node *node)
  Looks up the group node named \a name in the collection
  of all group nodes. If a match is not found, a new group
  node named \a name is created and inserted into the collection.
  Then append \a node to the group's members list, and append the
  group node to the member list of the \a node. The parent of the
  \a node is not changed by this function. Returns a pointer to
  the group node.
 */
 
/*! \fn CollectionNode *QDocDatabase::addToModule(const QString &name, Node *node)
  Looks up the module node named \a name in the collection
  of all module nodes. If a match is not found, a new module
  node named \a name is created and inserted into the collection.
  Then append \a node to the module's members list. The parent of
  \a node is not changed by this function. Returns the module node.
 */
 
/*! \fn Collection *QDocDatabase::addToQmlModule(const QString &name, Node *node)
  Looks up the QML module named \a name. If it isn't there,
  create it. Then append \a node to the QML module's member
  list. The parent of \a node is not changed by this function.
 */
 
/*! \fn QmlTypeNode *QDocDatabase::findQmlType(const QString &name)
  Returns the QML type node identified by the qualified
  QML type \a name, or \c nullptr if no type was found.
 */
 
/*!
  Returns the QML type node identified by the QML module id
  \a qmid and QML type \a name, or \c nullptr if no type
  was found.
 
  If the QML module id is empty, looks up the QML type by
  \a name only.
 */
QmlTypeNode *QDocDatabase::findQmlType(const QString &qmid, const QString &name)
{
    if (!qmid.isEmpty()) {
        if (auto *qcn = m_forest.lookupQmlType(qmid + u"::"_s + name); qcn)
            return qcn;
    }
 
    QStringList path(name);
    return static_cast<QmlTypeNode *>(m_forest.findNodeByNameAndType(path, &Node::isQmlType));
}
 
/*!
  Returns the QML type node identified by the QML module id
  constructed from the strings in the import \a record and the
  QML type \a name. Returns \c nullptr if no type was not found.
 */
QmlTypeNode *QDocDatabase::findQmlType(const ImportRec &record, const QString &name)
{
    if (!record.isEmpty()) {
        const QString qmName = record.m_importUri.isEmpty() ?
                record.m_moduleName : record.m_importUri;
        const QStringList dotSplit{name.split(QLatin1Char('.'))};
        for (const auto &namePart : dotSplit) {
            if (auto *qcn = m_forest.lookupQmlType(qmName + u"::"_s + namePart); qcn)
                return qcn;
        }
    }
    return nullptr;
}
 
/*!
  Returns the QML node identified by the QML module id \a qmid
  and \a name, searching in the primary tree only. If \a qmid
  is an empty string, searches for the node using name only.
 
  Returns \c nullptr if no node was found.
*/
QmlTypeNode *QDocDatabase::findQmlTypeInPrimaryTree(const QString &qmid, const QString &name)
{
    if (!qmid.isEmpty())
        return primaryTree()->lookupQmlType(qmid + u"::"_s + name);
    return static_cast<QmlTypeNode *>(primaryTreeRoot()->findChildNode(name, Node::QML, TypesOnly));
}
 
/*!
  This function calls a set of functions for each tree in the
  forest that has not already been analyzed. In this way, when
  running qdoc in \e singleExec mode, each tree is analyzed in
  turn, and its classes and types are added to the appropriate
  node maps.
 */
void QDocDatabase::processForest()
{
    processForest(&QDocDatabase::findAllClasses);
    processForest(&QDocDatabase::findAllFunctions);
    processForest(&QDocDatabase::findAllObsoleteThings);
    processForest(&QDocDatabase::findAllLegaleseTexts);
    processForest(&QDocDatabase::findAllSince);
    processForest(&QDocDatabase::findAllAttributions);
    resolveNamespaces();
}
 
/*!
  This function calls \a func for each tree in the forest,
  ensuring that \a func is called only once per tree.
 
  \sa processForest()
 */
void QDocDatabase::processForest(FindFunctionPtr func)
{
    Tree *t = m_forest.firstTree();
    while (t) {
        if (!m_completedFindFunctions.values(t).contains(func)) {
            (this->*(func))(t->root());
            m_completedFindFunctions.insert(t, func);
        }
        t = m_forest.nextTree();
    }
}
 
/*!
  Returns a reference to the collection of legalese texts.
 */
TextToNodeMap &QDocDatabase::getLegaleseTexts()
{
    processForest(&QDocDatabase::findAllLegaleseTexts);
    return m_legaleseTexts;
}
 
/*!
  Returns a reference to the map of C++ classes with obsolete members.
 */
NodeMultiMap &QDocDatabase::getClassesWithObsoleteMembers()
{
    processForest(&QDocDatabase::findAllObsoleteThings);
    return s_classesWithObsoleteMembers;
}
 
/*!
  Returns a reference to the map of obsolete QML types.
 */
NodeMultiMap &QDocDatabase::getObsoleteQmlTypes()
{
    processForest(&QDocDatabase::findAllObsoleteThings);
    return s_obsoleteQmlTypes;
}
 
/*!
  Returns a reference to the map of QML types with obsolete members.
 */
NodeMultiMap &QDocDatabase::getQmlTypesWithObsoleteMembers()
{
    processForest(&QDocDatabase::findAllObsoleteThings);
    return s_qmlTypesWithObsoleteMembers;
}
 
/*!
  Returns a reference to the map of QML basic types.
 */
NodeMultiMap &QDocDatabase::getQmlValueTypes()
{
    processForest(&QDocDatabase::findAllClasses);
    return s_qmlBasicTypes;
}
 
/*!
  Returns a reference to the multimap of QML types.
 */
NodeMultiMap &QDocDatabase::getQmlTypes()
{
    processForest(&QDocDatabase::findAllClasses);
    return s_qmlTypes;
}
 
/*!
  Returns a reference to the multimap of example nodes.
 */
NodeMultiMap &QDocDatabase::getExamples()
{
    processForest(&QDocDatabase::findAllClasses);
    return s_examples;
}
 
/*!
  Returns a reference to the multimap of attribution nodes.
 */
NodeMultiMap &QDocDatabase::getAttributions()
{
    processForest(&QDocDatabase::findAllAttributions);
    return m_attributions;
}
 
/*!
  Returns a reference to the map of obsolete C++ clases.
 */
NodeMultiMap &QDocDatabase::getObsoleteClasses()
{
    processForest(&QDocDatabase::findAllObsoleteThings);
    return s_obsoleteClasses;
}
 
/*!
  Returns a reference to the map of all C++ classes.
 */
NodeMultiMap &QDocDatabase::getCppClasses()
{
    processForest(&QDocDatabase::findAllClasses);
    return s_cppClasses;
}
 
/*!
  Returns the function index. This data structure is used to
  output the function index page.
 */
NodeMapMap &QDocDatabase::getFunctionIndex()
{
    processForest(&QDocDatabase::findAllFunctions);
    return m_functionIndex;
}
 
/*!
  Finds all the nodes containing legalese text and puts them
  in a map.
 */
void QDocDatabase::findAllLegaleseTexts(Aggregate *node)
{
    for (const auto &childNode : node->childNodes()) {
        if (childNode->isPrivate())
            continue;
        if (!childNode->doc().legaleseText().isEmpty())
            m_legaleseTexts.insert(childNode->doc().legaleseText(), childNode);
        if (childNode->isAggregate())
            findAllLegaleseTexts(static_cast<Aggregate *>(childNode));
    }
}
 
/*!
  \fn void QDocDatabase::findAllObsoleteThings(Aggregate *node)
 
  Finds all nodes with status = Deprecated and sorts them into
  maps. They can be C++ classes, QML types, or they can be
  functions, enum types, typedefs, methods, etc.
 */
 
/*!
  \fn void QDocDatabase::findAllSince(Aggregate *node)
 
  Finds all the nodes in \a node where a \e{since} command appeared
  in the qdoc comment and sorts them into maps according to the kind
  of node.
 
  This function is used for generating the "New Classes... in x.y"
  section on the \e{What's New in Qt x.y} page.
 */
 
/*!
  Find the \a key in the map of new class maps, and return a
  reference to the value, which is a NodeMap. If \a key is not
  found, return a reference to an empty NodeMap.
 */
const NodeMultiMap &QDocDatabase::getClassMap(const QString &key)
{
    processForest(&QDocDatabase::findAllSince);
    auto it = s_newClassMaps.constFind(key);
    return (it != s_newClassMaps.constEnd()) ? it.value() : emptyNodeMultiMap_;
}
 
/*!
  Find the \a key in the map of new QML type maps, and return a
  reference to the value, which is a NodeMap. If the \a key is not
  found, return a reference to an empty NodeMap.
 */
const NodeMultiMap &QDocDatabase::getQmlTypeMap(const QString &key)
{
    processForest(&QDocDatabase::findAllSince);
    auto it = s_newQmlTypeMaps.constFind(key);
    return (it != s_newQmlTypeMaps.constEnd()) ? it.value() : emptyNodeMultiMap_;
}
 
/*!
  Find the \a key in the map of new \e {since} maps, and return
  a reference to the value, which is a NodeMultiMap. If \a key
  is not found, return a reference to an empty NodeMultiMap.
 */
const NodeMultiMap &QDocDatabase::getSinceMap(const QString &key)
{
    processForest(&QDocDatabase::findAllSince);
    auto it = s_newSinceMaps.constFind(key);
    return (it != s_newSinceMaps.constEnd()) ? it.value() : emptyNodeMultiMap_;
}
 
/*!
  Performs several housekeeping tasks prior to generating the
  documentation. These tasks create required data structures
  and resolve links.
 */
void QDocDatabase::resolveStuff()
{
    const auto &config = Config::instance();
    if (config.dualExec() || config.preparing()) {
        // order matters
        primaryTree()->resolveBaseClasses(primaryTreeRoot());
        primaryTree()->resolvePropertyOverriddenFromPtrs(primaryTreeRoot());
        primaryTreeRoot()->resolveRelates();
        primaryTreeRoot()->normalizeOverloads();
        primaryTree()->markDontDocumentNodes();
        primaryTree()->removePrivateAndInternalBases(primaryTreeRoot());
        primaryTree()->resolveProperties();
        primaryTreeRoot()->markUndocumentedChildrenInternal();
        primaryTreeRoot()->resolveQmlInheritance();
        primaryTree()->resolveTargets(primaryTreeRoot());
        primaryTree()->resolveCppToQmlLinks();
        primaryTree()->resolveSince(*primaryTreeRoot());
    }
    if (config.singleExec() && config.generating()) {
        primaryTree()->resolveBaseClasses(primaryTreeRoot());
        primaryTree()->resolvePropertyOverriddenFromPtrs(primaryTreeRoot());
        primaryTreeRoot()->resolveQmlInheritance();
        primaryTree()->resolveCppToQmlLinks();
        primaryTree()->resolveSince(*primaryTreeRoot());
    }
    if (!config.preparing()) {
        resolveNamespaces();
        resolveProxies();
        resolveBaseClasses();
        updateNavigation();
    }
    if (config.dualExec())
        QDocIndexFiles::destroyQDocIndexFiles();
}
 
void QDocDatabase::resolveBaseClasses()
{
    Tree *t = m_forest.firstTree();
    while (t) {
        t->resolveBaseClasses(t->root());
        t = m_forest.nextTree();
    }
}
 
/*!
  Returns a reference to the namespace map. Constructs the
  namespace map if it hasn't been constructed yet.
 
  \note This function must not be called in the prepare phase.
 */
NodeMultiMap &QDocDatabase::getNamespaces()
{
    resolveNamespaces();
    return m_namespaceIndex;
}
 
/*!
  Multiple namespace nodes for namespace X can exist in the
  qdoc database in different trees. This function first finds
  all namespace nodes in all the trees and inserts them into
  a multimap. Then it combines all the namespace nodes that
  have the same name into a single namespace node of that
  name and inserts that combined namespace node into an index.
 */
void QDocDatabase::resolveNamespaces()
{
    if (!m_namespaceIndex.isEmpty())
        return;
 
    bool linkErrors = !Config::instance().get(CONFIG_NOLINKERRORS).asBool();
    NodeMultiMap namespaceMultimap;
    Tree *t = m_forest.firstTree();
    while (t) {
        t->root()->findAllNamespaces(namespaceMultimap);
        t = m_forest.nextTree();
    }
    const QList<QString> keys = namespaceMultimap.uniqueKeys();
    for (const QString &key : keys) {
        NamespaceNode *ns = nullptr;
        NamespaceNode *indexNamespace = nullptr;
        const NodeList namespaces = namespaceMultimap.values(key);
        qsizetype count = namespaceMultimap.remove(key);
        if (count > 0) {
            for (auto *node : namespaces) {
                ns = static_cast<NamespaceNode *>(node);
                if (ns->isDocumentedHere())
                    break;
                else if (ns->hadDoc())
                    indexNamespace = ns; // namespace was documented but in another tree
                ns = nullptr;
            }
            if (ns) {
                for (auto *node : namespaces) {
                    auto *nsNode = static_cast<NamespaceNode *>(node);
                    if (nsNode->hadDoc() && nsNode != ns) {
                        ns->doc().location().warning(
                                QStringLiteral("Namespace %1 documented more than once")
                                        .arg(nsNode->name()), QStringLiteral("also seen here: %1")
                                                .arg(nsNode->doc().location().toString()));
                    }
                }
            } else if (!indexNamespace) {
                // Warn about documented children in undocumented namespaces.
                // As the namespace can be documented outside this project,
                // skip the warning if -no-link-errors is set
                if (linkErrors) {
                    for (auto *node : namespaces) {
                        if (!node->isIndexNode())
                            static_cast<NamespaceNode *>(node)->reportDocumentedChildrenInUndocumentedNamespace();
                    }
                }
            } else {
                for (auto *node : namespaces) {
                    auto *nsNode = static_cast<NamespaceNode *>(node);
                    if (nsNode != indexNamespace)
                        nsNode->setDocNode(indexNamespace);
                }
            }
        }
        /*
          If there are multiple namespace nodes with the same
          name where one of them will be the main reference page
          for the namespace, include all nodes in the public
          API of the namespace.
         */
        if (ns && count > 1) {
            for (auto *node : namespaces) {
                auto *nameSpaceNode = static_cast<NamespaceNode *>(node);
                if (nameSpaceNode != ns) {
                    for (auto it = nameSpaceNode->constBegin(); it != nameSpaceNode->constEnd();
                         ++it) {
                        Node *anotherNs = *it;
                        if (anotherNs && anotherNs->isPublic() && !anotherNs->isInternal())
                            ns->includeChild(anotherNs);
                    }
                }
            }
        }
        /*
           Add the main namespace reference node to index, or the last seen
           namespace if the main one was not found.
        */
        if (!ns)
            ns = indexNamespace ? indexNamespace : static_cast<NamespaceNode *>(namespaces.last());
        m_namespaceIndex.insert(ns->name(), ns);
    }
}
 
/*!
  Each instance of class Tree that represents an index file
  must be traversed to find all instances of class ProxyNode.
  For each ProxyNode found, look up the ProxyNode's name in
  the primary Tree. If it is found, it means that the proxy
  node contains elements (normally just functions) that are
  documented in the module represented by the Tree containing
  the proxy node but that are related to the node we found in
  the primary tree.
 */
void QDocDatabase::resolveProxies()
{
    // The first tree is the primary tree.
    // Skip the primary tree.
    Tree *t = m_forest.firstTree();
    t = m_forest.nextTree();
    while (t) {
        const NodeList &proxies = t->proxies();
        if (!proxies.isEmpty()) {
            for (auto *node : proxies) {
                const auto *pn = static_cast<ProxyNode *>(node);
                if (pn->count() > 0) {
                    Aggregate *aggregate = primaryTree()->findAggregate(pn->name());
                    if (aggregate != nullptr)
                        aggregate->appendToRelatedByProxy(pn->childNodes());
                }
            }
        }
        t = m_forest.nextTree();
    }
}
 
/*!
  Finds the function node for the qualified function path in
  \a target and returns a pointer to it. The \a target is a
  function signature with or without parameters but without
  the return type.
 
  \a relative is the node in the primary tree where the search
  begins. It is not used in the other trees, if the node is not
  found in the primary tree. \a genus can be used to force the
  search to find a C++ function or a QML function.
 
  The entire forest is searched, but the first match is accepted.
 */
const FunctionNode *QDocDatabase::findFunctionNode(const QString &target, const Node *relative,
                                                   Node::Genus genus)
{
    QString signature;
    QString function = target;
    qsizetype length = target.size();
    if (function.endsWith("()"))
        function.chop(2);
    if (function.endsWith(QChar(')'))) {
        qsizetype position = function.lastIndexOf(QChar('('));
        signature = function.mid(position + 1, length - position - 2);
        function = function.left(position);
    }
    QStringList path = function.split("::");
    return m_forest.findFunctionNode(path, Parameters(signature), relative, genus);
}
 
/*!
  This function is called for autolinking to a \a type,
  which could be a function return type or a parameter
  type. The tree node that represents the \a type is
  returned. All the trees are searched until a match is
  found. When searching the primary tree, the search
  begins at \a relative and proceeds up the parent chain.
  When searching the index trees, the search begins at the
  root.
 */
const Node *QDocDatabase::findTypeNode(const QString &type, const Node *relative, Node::Genus genus)
{
    QStringList path = type.split("::");
    if ((path.size() == 1) && (path.at(0)[0].isLower() || path.at(0) == QString("T"))) {
        auto it = s_typeNodeMap.find(path.at(0));
        if (it != s_typeNodeMap.end())
            return it.value();
    }
    return m_forest.findTypeNode(path, relative, genus);
}
 
/*!
  Finds the node that will generate the documentation that
  contains the \a target and returns a pointer to it.
 
  Can this be improved by using the target map in Tree?
 */
const Node *QDocDatabase::findNodeForTarget(const QString &target, const Node *relative)
{
    const Node *node = nullptr;
    if (target.isEmpty())
        node = relative;
    else if (target.endsWith(".html"))
        node = findNodeByNameAndType(QStringList(target), &Node::isPageNode);
    else {
        QStringList path = target.split("::");
        int flags = SearchBaseClasses | SearchEnumValues;
        for (const auto *tree : searchOrder()) {
            const Node *n = tree->findNode(path, relative, flags, Node::DontCare);
            if (n)
                return n;
            relative = nullptr;
        }
        node = findPageNodeByTitle(target);
    }
    return node;
}
 
QStringList QDocDatabase::groupNamesForNode(Node *node)
{
    QStringList result;
    CNMap *m = primaryTree()->getCollectionMap(Node::Group);
 
    if (!m)
        return result;
 
    for (auto it = m->cbegin(); it != m->cend(); ++it)
        if (it.value()->members().contains(node))
            result << it.key();
 
    return result;
}
 
/*!
  Reads and parses the qdoc index files listed in \a indexFiles.
 */
void QDocDatabase::readIndexes(const QStringList &indexFiles)
{
    QStringList filesToRead;
    for (const QString &file : indexFiles) {
        QString fn = file.mid(file.lastIndexOf(QChar('/')) + 1);
        if (!isLoaded(fn))
            filesToRead << file;
        else
            qCCritical(lcQdoc) << "Index file" << file << "is already in memory.";
    }
    QDocIndexFiles::qdocIndexFiles()->readIndexes(filesToRead);
}
 
/*!
  Generates a qdoc index file and write it to \a fileName. The
  index file is generated with the parameters \a url and \a title,
  using the generator \a g.
 */
void QDocDatabase::generateIndex(const QString &fileName, const QString &url, const QString &title,
                                 Generator *g)
{
    QString t = fileName.mid(fileName.lastIndexOf(QChar('/')) + 1);
    primaryTree()->setIndexFileName(t);
    QDocIndexFiles::qdocIndexFiles()->generateIndex(fileName, url, title, g);
    QDocIndexFiles::destroyQDocIndexFiles();
}
 
/*!
    Returns the collection node representing the module that \a relative
    node belongs to, or \c nullptr if there is no such module in the
    primary tree.
*/
const CollectionNode *QDocDatabase::getModuleNode(const Node *relative)
{
    Node::NodeType moduleType{Node::Module};
    QString moduleName;
    switch (relative->genus())
    {
    case Node::CPP:
        moduleType = Node::Module;
        moduleName = relative->physicalModuleName();
        break;
    case Node::QML:
        moduleType = Node::QmlModule;
        moduleName = relative->logicalModuleName();
        break;
    default:
        return nullptr;
    }
    if (moduleName.isEmpty())
        return nullptr;
 
    return primaryTree()->getCollection(moduleName, moduleType);
}
 
/*!
  Finds all the collection nodes of the specified \a type
  and merges them into the collection node map \a cnm. Nodes
  that match the \a relative node are not included.
 */
void QDocDatabase::mergeCollections(Node::NodeType type, CNMap &cnm, const Node *relative)
{
    cnm.clear();
    CNMultiMap cnmm;
    for (auto *tree : searchOrder()) {
        CNMap *m = tree->getCollectionMap(type);
        if (m && !m->isEmpty()) {
            for (auto it = m->cbegin(); it != m->cend(); ++it) {
                if (!it.value()->isInternal())
                    cnmm.insert(it.key(), it.value());
            }
        }
    }
    if (cnmm.isEmpty())
        return;
    static const QRegularExpression singleDigit("\\b([0-9])\\b");
    const QStringList keys = cnmm.uniqueKeys();
    for (const auto &key : keys) {
        const QList<CollectionNode *> values = cnmm.values(key);
        CollectionNode *n = nullptr;
        for (auto *value : values) {
            if (value && value->wasSeen() && value != relative) {
                n = value;
                break;
            }
        }
        if (n) {
            if (values.size() > 1) {
                for (CollectionNode *value : values) {
                    if (value != n) {
                        // Allow multiple (major) versions of QML modules
                        if ((n->isQmlModule())
                            && n->logicalModuleIdentifier() != value->logicalModuleIdentifier()) {
                            if (value->wasSeen() && value != relative)
                                cnm.insert(value->fullTitle().toLower(), value);
                            continue;
                        }
                        for (Node *t : value->members())
                            n->addMember(t);
                    }
                }
            }
            QString sortKey = n->fullTitle().toLower();
            if (sortKey.startsWith("the "))
                sortKey.remove(0, 4);
            sortKey.replace(singleDigit, "0\\1");
            cnm.insert(sortKey, n);
        }
    }
}
 
/*!
  Finds all the collection nodes with the same name
  and type as \a c and merges their members into the
  members list of \a c.
 
  For QML modules, only nodes with matching
  module identifiers are merged to avoid merging
  modules with different (major) versions.
 */
void QDocDatabase::mergeCollections(CollectionNode *c)
{
    if (c == nullptr)
        return;
 
    // REMARK: This form of merging is usually called during the
    // generation phase om-the-fly when a source-of-truth collection
    // is required.
    // In practice, this means a collection could be merged many, many
    // times during the lifetime of a generation.
    // To avoid repeating the merging process each time, which could
    // be time consuming, we use a small flag that is set directly on
    // the collection to bail-out early.
    //
    // The merging process is only meaningful for collections when the
    // collection references are spread troughout multiple projects.
    // The part of information that exists in other project is read
    // before the generation phase, such that when the generation
    // phase comes, we already have all the information we need for
    // merging such that we can consider all version of a certain
    // collection node immutable, making the caching inherently
    // correct at any point of the generation.
    //
    // This implies that this operation is unsafe if it is performed
    // before all the index files are loaded.
    // Indeed, this is a prerequisite, with the current structure, to
    // perform this optmization.
    //
    // At the current time, this is true and is expected not to
    // change.
    //
    // Do note that this is not applied to the other overload of
    // mergeCollections as we cannot as safely ensure its consistency
    // and, as the result of the merging depends on multiple
    // parameters, it would require an actual memoization of the call.
    //
    // Note that this is a defensive optimization and we are assuming
    // that it is effective based on heuristical data. As this is
    // expected to disappear, at least in its current form, in the
    // future, a more thorough analysis was not performed.
    if (c->isMerged()) {
        return;
    }
 
    for (auto *tree : searchOrder()) {
        CollectionNode *cn = tree->getCollection(c->name(), c->nodeType());
        if (cn && cn != c) {
            if ((cn->isQmlModule())
                && cn->logicalModuleIdentifier() != c->logicalModuleIdentifier())
                continue;
 
            for (auto *node : cn->members())
                c->addMember(node);
 
            // REMARK: The merging process is performed to ensure that
            // references to the collection in external projects are
            // taken into account before consuming the collection.
            //
            // This works by having QDoc construct empty collections
            // as soon as a reference to a collection is encountered
            // and filling details later on when its definition is
            // found.
            //
            // This initially-empty collection is always saved to the
            // primaryTree and it is the collection that is directly
            // accessible to consumers during the generation process.
            //
            // Nonetheless, when the definition for the collection is
            // not in the same project as the one that is being
            // compiled, its details will never be filled in.
            //
            // Indeed, the details will live in the index file for the
            // project where the collection is defined, if any, and
            // the node for it, which has complete information, will
            // live in some non-primaryTree.
            //
            // The merging process itself is used by consumers during
            // the generation process because they access the
            // primaryTree version of the collection expecting a
            // source-of-truth.
            // To ensure that this is the case for usages that
            // requires linking, we need to merge not only the members
            // of the collection that reside in external versions of
            // the collection; but some of the data that reside in the
            // definition of the collection intself, namely the title
            // and the url.
            //
            // A collection that contains the data of a definition is
            // always marked as seen, hence we use that to discern
            // whether we are working with a placeholder node or not,
            // and fill in the data if we encounter a node that
            // represents a definition.
            //
            // The way in which QDoc works implies that collection are
            // globally scoped between projects.
            // The repetition of the definition for the same
            // collection is warned for as a duplicate documentation,
            // such that we can expect a single valid source of truth
            // for a given collection in each project.
            // It is currently unknown if this warning is applicable
            // when the repeated collection is defined in two
            // different projects.
            //
            // As QDoc implicitly would not correctly support this
            // case, we assume that only one declaration exists for
            // each collection, such that the first encoutered one
            // must be the source of truth and that there is no need
            // to copy any data after the first copy is performed.
            // KLUDGE: Note that this process is done as a hackish
            // solution to QTBUG-104237 and should not be considered
            // final or dependable.
            if (!c->wasSeen() && cn->wasSeen()) {
                c->markSeen();
                c->setTitle(cn->title());
                c->setUrl(cn->url());
            }
        }
    }
 
    c->markMerged();
}
 
/*!
  Searches for the node that matches the path in \a atom and the
  specified \a genus. The \a relative node is used if the first
  leg of the path is empty, i.e. if the path begins with '#'.
  The function also sets \a ref if there remains an unused leg
  in the path after the node is found. The node is returned as
  well as the \a ref. If the returned node pointer is null,
  \a ref is also not valid.
 */
const Node *QDocDatabase::findNodeForAtom(const Atom *a, const Node *relative, QString &ref,
                                          Node::Genus genus)
{
    const Node *node = nullptr;
 
    Atom *atom = const_cast<Atom *>(a);
    QStringList targetPath = atom->string().split(QLatin1Char('#'));
    QString first = targetPath.first().trimmed();
 
    Tree *domain = nullptr;
 
    if (atom->isLinkAtom()) {
        domain = atom->domain();
        genus = atom->genus();
    }
 
    if (first.isEmpty())
        node = relative; // search for a target on the current page.
    else if (domain) {
        if (first.endsWith(".html"))
            node = domain->findNodeByNameAndType(QStringList(first), &Node::isPageNode);
        else if (first.endsWith(QChar(')'))) {
            QString signature;
            QString function = first;
            qsizetype length = first.size();
            if (function.endsWith("()"))
                function.chop(2);
            if (function.endsWith(QChar(')'))) {
                qsizetype position = function.lastIndexOf(QChar('('));
                signature = function.mid(position + 1, length - position - 2);
                function = function.left(position);
            }
            QStringList path = function.split("::");
            node = domain->findFunctionNode(path, Parameters(signature), nullptr, genus);
        }
        if (node == nullptr) {
            int flags = SearchBaseClasses | SearchEnumValues;
            QStringList nodePath = first.split("::");
            QString target;
            targetPath.removeFirst();
            if (!targetPath.isEmpty())
                target = targetPath.takeFirst();
            if (relative && relative->tree()->physicalModuleName() != domain->physicalModuleName())
                relative = nullptr;
            return domain->findNodeForTarget(nodePath, target, relative, flags, genus, ref);
        }
    } else {
        if (first.endsWith(".html"))
            node = findNodeByNameAndType(QStringList(first), &Node::isPageNode);
        else if (first.endsWith(QChar(')')))
            node = findFunctionNode(first, relative, genus);
        if (node == nullptr)
            return findNodeForTarget(targetPath, relative, genus, ref);
    }
 
    if (node != nullptr && ref.isEmpty()) {
        if (!node->url().isEmpty())
            return node;
        targetPath.removeFirst();
        if (!targetPath.isEmpty()) {
            ref = node->root()->tree()->getRef(targetPath.first(), node);
            if (ref.isEmpty())
                node = nullptr;
        }
    }
    return node;
}
 
/*!
    Updates navigation (previous/next page links and the navigation parent)
    for pages listed in the TOC, specified by the \c navigation.toctitles
    configuration variable.
 
    if \c navigation.toctitles.inclusive is \c true, include also the TOC
    page(s) themselves as a 'root' item in the navigation bar (breadcrumbs)
    that are generated for HTML output.
*/
void QDocDatabase::updateNavigation()
{
    // Restrict searching only to the local (primary) tree
    QList<Tree *> searchOrder = this->searchOrder();
    setLocalSearch();
 
    const QString configVar = CONFIG_NAVIGATION +
                              Config::dot +
                              CONFIG_TOCTITLES;
 
    // TODO: [direct-configuration-access]
    // The configuration is currently a singleton with some generally
    // global mutable state.
    //
    // Accessing the data in this form complicates testing and
    // requires tests that inhibit any test parallelization, as the
    // tests are not self contained.
    //
    // This should be generally avoived. Possibly, we should strive
    // for Config to be a POD type that generally is scoped to
    // main and whose data is destructured into dependencies when
    // the dependencies are constructed.
    bool inclusive{Config::instance().get(
            configVar + Config::dot + CONFIG_INCLUSIVE).asBool()};
 
    // TODO: [direct-configuration-access]
    const auto tocTitles{Config::instance().get(configVar).asStringList()};
 
    for (const auto &tocTitle : tocTitles) {
        if (const auto candidateTarget = findNodeForTarget(tocTitle, nullptr); candidateTarget && candidateTarget->isPageNode()) {
            auto tocPage{static_cast<const PageNode*>(candidateTarget)};
 
            Text body = tocPage->doc().body();
 
            auto *atom = body.firstAtom();
 
            std::pair<PageNode *, Atom *> prev { nullptr, nullptr };
 
            std::stack<const PageNode *> tocStack;
            tocStack.push(inclusive ? tocPage : nullptr);
 
            bool inItem = false;
 
            // TODO: Understand how much we use this form of looping over atoms.
            // If it is used a few times we might consider providing
            // an iterator for Text to make use of a simpler
            // range-for loop.
            while (atom) {
                switch (atom->type()) {
                    case Atom::ListItemLeft:
                        // Not known if we're going to have a link, push a temporary
                        tocStack.push(nullptr);
                        inItem = true;
                        break;
                    case Atom::ListItemRight:
                        tocStack.pop();
                        inItem = false;
                        break;
                    case Atom::Link: {
                        if (!inItem)
                            break;
 
                        // TODO: [unnecessary-output-parameter]
                        // We currently need an lvalue string to
                        // pass to findNodeForAtom, as the
                        // outparameter ref.
                        //
                        // Apart from the general problems with output
                        // parameters, we shouldn't be forced to
                        // instanciate an unnecessary object at call
                        // site.
                        //
                        // Understand what the correct way to avoid this is.
                        // This requires changes to findNodeForAtom
                        // and should be addressed in the context of
                        // revising that method.
                        QString unused{};
                        // TODO: Having to const cast is really a code
                        // smell and could result in undefined
                        // behavior in some specific cases (e.g point
                        // to something that is actually const).
                        //
                        // We should understand how to sequence the
                        // code so that we have access to mutable data
                        // when we need it and "freeze" the data
                        // afterwards.
                        //
                        // If it we expect this form of mutability at
                        // this point we should expose a non-const API
                        // for the database, possibly limited to a
                        // very specific scope of execution.
                        //
                        // Understand what the correct sequencing for
                        // this processing is and revise this part.
                        auto candidatePage = const_cast<Node *>(findNodeForAtom(atom, nullptr, unused));
                        if (!candidatePage || !candidatePage->isPageNode()) break;
 
                        auto page{static_cast<PageNode*>(candidatePage)};
 
                        // ignore self-references
                        if (page == prev.first) break;
 
                        if (prev.first) {
                            prev.first->setLink(
                                Node::NextLink,
                                page->title(),
                                // TODO: [possible-assertion-failure][imprecise-types][atoms-link]
                                // As with other structures in QDoc we
                                // are able to call methods that are
                                // valid only on very specific states.
                                //
                                // For some of those calls we have
                                // some defensive programming measures
                                // that allow us to at least identify
                                // the error during debugging, while
                                // for others this may currently hide
                                // some logic error.
                                //
                                // To avoid those cases, we should
                                // strive to move those cases to a
                                // compilation error, requiring a
                                // statically analyzable state that
                                // represents the current model.
                                //
                                // This would ensure that those
                                // lingering class of bugs are
                                // eliminated completely, forces a
                                // more explicit codebase where the
                                // current capabilities do not depend
                                // on runtime values might not be
                                // generally visible, and does not
                                // require us to incur into the
                                // required state, which may be rare,
                                // simplifying our abilities to
                                // evaluate all possible states.
                                //
                                // For linking atoms, LinkAtom is
                                // available and might be a good
                                // enough solution to move linkText
                                // to.
                                atom->linkText()
                            );
                            page->setLink(
                                Node::PreviousLink,
                                prev.first->title(),
                                // TODO: [possible-assertion-failure][imprecise-types][atoms-link]
                                prev.second->linkText()
                            );
                        }
 
                        if (page == tocPage)
                            break;
 
                        // Find the navigation parent from the stack; we may have null pointers
                        // for non-link list items, so skip those.
                        qsizetype popped = 0;
                        while (tocStack.size() > 1 && !tocStack.top()) {
                            tocStack.pop();
                            ++popped;
                        }
 
                        page->setNavigationParent(tocStack.empty() ? nullptr : tocStack.top());
 
                        while (--popped > 0)
                            tocStack.push(nullptr);
 
                        tocStack.push(page);
                        prev = { page, atom };
                    }
                        break;
                    default:
                        break;
                }
 
                atom = atom->next();
            }
        } else {
            Config::instance().get(configVar).location()
                    .warning(QStringLiteral("Failed to find table of contents with title '%1'")
                            .arg(tocTitle));
        }
    }
 
    // Restore search order
    setSearchOrder(searchOrder);
}
 
QT_END_NAMESPACE