Uploaded image for project: 'Qt'
  1. Qt
  2. QTBUG-141606

QDoc: Add hierarchical QML type member search for link resolution

XMLWordPrintable

    • Icon: Suggestion Suggestion
    • Resolution: Unresolved
    • Icon: P3: Somewhat important P3: Somewhat important
    • None
    • None
    • Build tools: qdoc
    • 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.

        No reviews matched the request. Check your Options in the drop-down menu of this sections header.

            docinfrastructure Documentation Infrastructure Team
            paulwicking Paul Wicking
            Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

              Created:
              Updated:

                There are 2 open Gerrit changes