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

QDoc: Refactor private node inclusion logic to eliminate code duplication

XMLWordPrintable

    • 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.

        For Gerrit Dashboard: QTBUG-140077
        # Subject Branch Project Status CR V

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

              Created:
              Updated:
              Resolved: