-
Task
-
Resolution: Fixed
-
P1: Critical
-
None
-
cf8924347 (dev), a76576156 (dev), 7551c9b3b (dev), 211d38ccc (dev), bd6bba9bb (dev), 8af2025e1 (dev), 73611aa7c (dev), a5f9a5a13 (dev), 0ce529c92 (dev)
-
DaVinci 124
Since including private access members for consideration when generating documentation, the QDoc codebase now contains three nearly identical functions for determining whether private nodes should be included in documentation:
- shouldIncludePrivateNode() (duplicated in two locations)
- shouldWarnAboutUndocumentedPrivateNode()
These functions contain the same branching logic yet are used for different purposes. This creates a maintenance burden and risk of inconsistency when inclusion rules need to be modified.
We can implement the Strategy pattern to centralize inclusion policy logic:
- Extract configuration state into InclusionPolicy POD struct
- Extract node state into NodeContext POD struct
- Implement pure inclusion checking functions operating on PODs
- Use QFlags for efficient policy matching
The benefits of this approach include having a single source of truth for inclusion logic. This will become more important as we consider other, similar configurable inclusion rules, for example for the re-enablement of including \internal documentation. The multiple light-weight POD structure allows for reduced coupling between components and improved testability. Also, relying on an established and well-known pattern makes it a clear extension point for future rules and code maintainers.
- resulted from
-
QTBUG-99553 qdoc: Hidden friends not visible if declared as private
-
- Closed
-
-
QTBUG-58805 Cannot document private virtual (abstract) methods with QDoc
-
- Closed
-
-
QTBUG-114877 QDoc doesn't catch private pure virtual methods
-
- Closed
-
-
QTBUG-63977 [QDOC] Add a setting to document private class members
-
- Closed
-
For Gerrit Dashboard: QTBUG-140077 | ||||||
---|---|---|---|---|---|---|
# | Subject | Branch | Project | Status | CR | V |
674945,3 | QDoc: Add inclusion policy infrastructure | dev | qt/qttools | Status: MERGED | +2 | 0 |
674946,3 | QDoc: Add node context for policy decisions | dev | qt/qttools | Status: MERGED | +2 | 0 |
674947,3 | QDoc: Centralize inclusion decision logic | dev | qt/qttools | Status: MERGED | +2 | 0 |
674948,3 | QDoc: Bridge configuration to inclusion policy | dev | qt/qttools | Status: MERGED | +2 | 0 |
674949,3 | QDoc: Eliminate duplicate inclusion checks | dev | qt/qttools | Status: MERGED | +2 | 0 |
674951,8 | QDoc: Unify inclusion policy API naming and usage | dev | qt/qttools | Status: MERGED | +2 | 0 |
675080,5 | QDoc: Document QDoc's inclusion strategy | dev | qt/qttools | Status: MERGED | +2 | 0 |
675298,4 | QDoc: Test inclusion strategy | dev | qt/qttools | Status: MERGED | +2 | 0 |
675491,3 | QDoc: Update documentation for NodeContext | dev | qt/qttools | Status: MERGED | +2 | 0 |