-
Suggestion
-
Resolution: Unresolved
-
P3: Somewhat important
-
None
-
None
-
None
QDoc's link resolution currently lacks hierarchical search support for QML types. This causes an asymmetry with C++ class handling. When documenting a QML type that inherits from a base type, simple links (e.g., \l propertyName) cannot resolve to inherited members.
Current behavior
C++ classes benefit from base class searching during link resolution (see tree.cpp:648-660, 719-730) via the SearchBaseClasses flag. This allows \l font from QToolButton documentation to resolve to the inherited QWidget::font property (fixed in QTBUG-72107).
QML types have no equivalent mechanism. The qmlBaseNode() accessor exists for traversing inheritance chains, but is never used during link resolution. Links to inherited QML properties/methods require fully-qualified names.
Expected behavior
QML link resolution should mirror C++ behavior:
1. When resolving a link from within a QML type's documentation context;
2. Search the type's own members first,
3. Then traverse the qmlBaseNode() chain to search inherited members,
4. Fall back to global targets only if hierarchical search finds nothing.
Implementation notes
The fix locations are identical to QTBUG-72107:
- tree.cpp:matchPathAndTarget() - Add QML equivalent of lines 648-660.
- tree.cpp:findNode() - Add QML equivalent of lines 719-730.
- Check node->isQmlType() and traverse qmlBaseNode() chain.
QTBUG-61571 documents that QDoc's QmlTypeMap silently drops name collisions (tree.cpp:1252-1256). Only the first type with a given name is stored per module. Adding hierarchical search WITHOUT fixing collision handling would cause links to resolve to the WRONG type when names collide across modules. These issues must therefore be addressed together;
1. Fix QmlTypeMap to use QMultiMap and store all types (QTBUG-61571 foundation).
2. Add QML base type search (this feature).
3. Implement import-aware disambiguation to prefer types from the same module.
Implementing only this suggestion alone could be problematic as it could make "Shape" links from QtQuick.Shapes.Path resolve to ParticlePlugin's Shape instead of QtQuick.Shapes.Shape.
- relates to
-
QTBUG-61571 Improvements to doc handling of QML types with same name and different imports
-
- Open
-
-
QTBUG-72107 \l font in QToolButton's documentation results in a link to the font row in the stylesheet reference documentation
-
- In Review
-