-
Bug
-
Resolution: Fixed
-
P0: Blocker
-
6.11
-
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
- Create a function documented with \internal containing a typo in a \a parameter name.
- Run QDoc with showinternal=false (default).
- 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.
- resulted from
-
QTBUG-139658 QDoc: Restore showinternal functionality for internal documentation generation
-
- In Progress
-
-
QTBUG-128730 Revisit how we build and use qdoc for documentation building
-
- Closed
-