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 |