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

QDoc: Implement unified inclusion strategy pattern for node filtering

XMLWordPrintable

    • Icon: Task Task
    • Resolution: Unresolved
    • Icon: P2: Important P2: Important
    • None
    • None
    • Build tools: qdoc
    • 75a27a334 (dev), 6feb8902e (dev), de7934bc6 (dev), a976a6655 (dev), a99c2a26a (dev), 00753687e (dev), 86af659da (dev), 72f6931c7 (dev), 694f27221 (dev), dcbacfcf8 (dev)
    • DaVinci 125

      QDoc currently has inconsistent and scattered logic for determining which nodes
      should be included in documentation generation. Different components use ad-hoc
      checks that combine direct `isInternal()` calls with `Config::showInternal()`
      queries, separate private member inclusion flags (`includePrivate*`),
      generator-specific caching of configuration state, and duplicated filtering
      logic across HTML, DocBook, and WebXML generators.

      This results in needless code duplication across generators and filters. It may
      also possibly be the source of inconsistent behavior between output formats,
      certainly as the generators diverge in features. Extending inclusion rules
      becomes difficult, and testability of inclusion logic is practically
      non-existent. It also causes tight coupling between generators and
      configuration.

      Recently, a series of changes introduced the inclusion strategy pattern to the
      QDoc codebase. It's meant to:

      1. Centralize inclusion policy in `InclusionPolicy` struct containing all relevant flags
      2. Standardize node context in `NodeContext` struct capturing node characteristics
      3. Provide unified filtering through `InclusionFilter` with intention-revealing methods
      4. Use efficient flag-based matching with `InclusionFlags` enum for performance
      5. Eliminate scattered checks by migrating all components to use the centralized system

      This task serves as documentation for the effort to transition QDoc towards
      making full use of the inclusion strategy pattern.

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

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

              Created:
              Updated: