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

QDoc generates warnings for documentation typos in \internal blocks when showinternal=false

XMLWordPrintable

    • cc8d7c3e9 (dev)
    • DaVinci 124

      After commit e601393136094f7dd8cc2a4851101f96ccec0bbc ("QDoc: Don't force private access for \internal nodes"), QDoc now warns about documentation issues (such as parameter name typos in \a commands) within \internal documentation blocks, even when showinternal=false.

      Steps to Reproduce

      1. Create a function documented with \internal containing a typo in a \a parameter name.
      2. Run QDoc with showinternal=false (default).
      3. Observe warnings about parameter mismatches in internal documentation.

      Example:
      /*!
          \internal
          This function takes \a expecetedVal (typo: should be expectedVal)
      */
      {{bool compare_helper(const char* expectedVal) { ... }}}

      Expected Behavior

      No warnings should be generated for documentation within \internal blocks when showinternal=false, since this documentation is not processed for output.

      Actual Behavior

      QDoc warns: "No such parameter 'expecetedVal' in compare_helper(const char*). Maybe you meant 'expectedVal'?"

      Root Cause

      The commit e601393136094f7dd8cc2a4851101f96ccec0bbc separated internal status from private access. Previously, internal nodes were also marked as private, so InclusionFilter::requiresDocumentation() would exclude them from warnings via the !context.isPrivate check. Now that internal nodes are not automatically private, they bypass this check and trigger parameter validation warnings.

      Technical Details

      • InclusionFilter::requiresDocumentation() only checks context.isPrivate but ignores context.isInternal.
      • Parameter validation in Generator::generateBody() (lines 776-805) runs unconditionally without checking inclusion policies.
      • This creates inconsistent behavior: some warnings respect showinternal policy, others don't.

      Impact

      • Breaks builds with strict warning policies when internal documentation contains typos. This is in particular a problem in COIN, as QDoc from dev branch runs on integrations in all branches.
      • Inconsistent warning behavior across different types of documentation issues.
      • Forces developers to fix documentation that won't be generated.

        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