Revision control
++ # Node System and Tree Architecture
++
++ ## Node System: How QDoc Models Documentation
++
++ QDoc builds an in-memory **tree of nodes** representing every documentable entity.
++
++ ### Node Hierarchy
++
++ ```
++ INode (interface)
++ └─ Node (base class)
++ ├─ PageNode (generates output files)
++ │ ├─ CollectionNode (Module, Group, QmlModule)
++ │ ├─ ExampleNode
++ │ └─ ExternalPageNode
++ │
++ └─ Aggregate (can have children)
++ ├─ NamespaceNode
++ ├─ ClassNode (class, struct, union)
++ ├─ HeaderNode
++ └─ QmlTypeNode
++ ```
++
++ ### Node Types by Category
++
++ | Category | Node Types |
++ |----------|------------|
++ | **C++** | Namespace, Class, Struct, Union, Function, Property, Variable, Enum, Typedef |
++ | **QML** | QmlType, QmlValueType, QmlProperty, QmlMethod, QmlSignal, QmlEnum, QmlModule |
++ | **Documentation** | Page, Example, ExternalPage, Group, Module |
++
++ ### Genus System
++
++ QDoc classifies nodes by **genus** for targeted searches:
++ - `CPP` (0x1) - C++ entities
++ - `QML` (0x4) - QML entities
++ - `DOC` (0x8) - Documentation pages
++ - `API` (CPP|QML) - Any code entity
++ - `DontCare` (0x0) - Match anything
++
++ ---
++
++ ## Topic Commands Create Nodes
++
++ When QDoc encounters a topic command, it creates the corresponding node:
++
++ | Command | Node Created | Example |
++ |---------|--------------|---------|
++ | `\class` | ClassNode | `\class QWidget` |
++ | `\fn` | FunctionNode | `\fn void QWidget::show()` |
++ | `\enum` | EnumNode | `\enum Qt::AlignmentFlag` |
++ | `\property` | PropertyNode | `\property QWidget::visible` |
++ | `\qmltype` | QmlTypeNode | `\qmltype Rectangle` |
++ | `\qmlproperty` | QmlPropertyNode | `\qmlproperty int Item::width` |
++ | `\qmlmethod` | FunctionNode (QML) | `\qmlmethod void Item::update()` |
++ | `\qmlsignal` | FunctionNode (QML) | `\qmlsignal Item::clicked()` |
++ | `\page` | PageNode | `\page overview.html` |
++ | `\module` | CollectionNode | `\module QtCore` |
++ | `\group` | CollectionNode | `\group painting` |
++
++ **Critical**: Names must be **fully qualified**:
++ ```cpp
++ // Correct
++ \fn void QGraphicsWidget::setWindowFlags(Qt::WindowFlags flags)
++
++ // Wrong - missing class prefix
++ \fn void setWindowFlags(Qt::WindowFlags flags)
++ ```
++
++ ### QML Method Return Types (IMPORTANT)
++
++ **`\qmlmethod` commands MUST include a return type** or the method won't be indexed:
++
++ ```cpp
++ // CORRECT - will be indexed and linkable
++ \qmlmethod void TextToSpeech::say(string text)
++ \qmlmethod list<voice> TextToSpeech::availableVoices()
++
++ // WRONG - will NOT be indexed, links will fail
++ \qmlmethod TextToSpeech::say(string text)
++ ```
++
++ **Root cause**: `cppcodeparser.cpp:726-742` parses `\qmlmethod` arguments by splitting on `::`.
++ The module name is only extracted when there are 3+ parts (return type + type + method).
++ Without a return type, the method is added to an orphan QmlTypeNode not linked to the module.
++
++ **Fix**: Add `void` for void-returning methods. This is the established Qt pattern used in
++ Qt3D, QtCharts, QtMultimedia, and other modules.
++
++ ---
++
++ ## Tree and Forest Architecture
++
++ ### Single Module = One Tree
++
++ Each module builds a **Tree** with:
++ - `m_root` - Root NamespaceNode
++ - `m_nodesByTargetRef` - Targets indexed by anchor
++ - `m_nodesByTargetTitle` - Targets indexed by title
++ - `m_qmlTypeMap` - QML type lookup
++
++ ### Multiple Modules = Forest
++
++ **QDocForest** manages multiple trees:
++ ```
++ QDocDatabase (singleton)
++ └─ QDocForest
++ ├─ Primary Tree (current module being documented)
++ └─ Index Trees (loaded from .index files of dependencies)
++ ```
++
++ When resolving links, QDoc searches trees in order until a match is found.
++
++ ---
++
++ ## Key Source Files
++
++ | File | Purpose |
++ |------|---------|
++ | `node.h/cpp` | Base Node class, type definitions |
++ | `aggregate.h/cpp` | Parent nodes with children |
++ | `tree.h/cpp` | Tree structure, target resolution |
++ | `qdocdatabase.h/cpp` | Forest management, resolution pipeline |
++ | `pagenode.h` | Documentation-generating nodes |