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

QDoc reports false positive warnings for properties from included dependency headers

XMLWordPrintable

    • 179518531 (dev), 76480d316 (dev)
    • DaVinci 128

      When building documentation for a Qt module that includes headers from dependency modules, QDoc generates false positive "undocumented property" warnings if both modules contain headers with identical filenames.

      Steps to Reproduce:
      1. Build Qt3D documentation (which depends on QtCore).
      2. Qt3D has: qt3d/src/animation/frontend/qabstractanimation.h
      3. QtCore has: qtbase/src/corelib/animation/qabstractanimation.h
      4. Qt3D code includes <QtCore/QAbstractAnimation>.

      Expected Result:
      No warnings about QAbstractAnimation properties, since they are documented in QtCore

      Actual Result:
      QDoc warns:
      [Qt3D] (qdoc) warning: Undocumented property 'QAbstractAnimation::loopCount'
      [Qt3D] (qdoc) warning: Undocumented property 'QAbstractAnimation::currentTime'

      Root Cause:
      ClangVisitor matches headers by filename only when determining if a header is "interesting" (belongs to the current module being documented). When it encounters an #include, it matches "qabstractanimation.h" from QtCore because Qt3D also has a file with that name. This causes ClangVisitor to parse QtCore's header and create PropertyNodes in Qt3D's documentation tree. These nodes lack documentation comments (which exist only in QtCore), triggering false positive warnings.

      Impact:

      • False positive warnings clutter build logs.
      • With warninglimit=0, documentation builds fail incorrectly.
      • Makes it difficult to identify genuine documentation issues.
      • Affects any module with headers that have the same name as dependency headers.

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

            paulwicking Paul Wicking
            paulwicking Paul Wicking
            Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

              Created:
              Updated:
              Resolved:

                There are no open Gerrit changes