inclusionstrategy.qdoc

Go to the documentation of this file.

// Copyright (C) 2025 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
/*!
    \headerfile inclusionflags.h
    \title Inclusion Strategy Components
    \inmodule QDoc
    \brief Defines types for controlling documentation inclusion of private and internal API elements.
 
    The inclusion strategy system provides a centralized way to determine which
    documentation nodes should be included in generated output. It consists of
    three main components that work together to implement inclusion decisions:
 
    \list
    \li \l{InclusionFlag} and \l{InclusionFlags} - Flags representing different types of private API
    \li \l{InclusionPolicy} - Configuration-driven policy for what to include
    \li \l{NodeContext} - Lightweight node state capture for policy evaluation
    \endlist
 
    This system replaces scattered inclusion checks throughout QDoc with a
    unified approach, ensuring consistent behavior across all output generators.
*/
 
/*!
    \enum InclusionFlag
    \headerfile inclusionflags.h
    \inmodule QDoc
    \brief Flags for different categories of private API elements.
 
    These flags represent different types of private API elements that can be
    selectively included in documentation based on configuration settings.
 
    \value PrivateFunction
           Private functions and methods. Corresponds to the
           \c{includeprivate.functions} configuration option, or if unset,
           to the general \c{includeprivate} option.
 
    \value PrivateType
           Private types including classes, enums, and typedefs. Corresponds to
           the \c{includeprivate.types} configuration option, or if unset,
           to the general \c{includeprivate} option.
 
    \value PrivateVariable
           Private member variables and properties. Corresponds to the
           \c{includeprivate.variables} configuration option, or if unset,
           to the general \c{includeprivate} option.
 
    \value Internal
           Internal API elements explicitly marked with \\internal.
           Corresponds to the \c{showinternal} configuration option and command
           line flag, together with \c InternalAuto.
 
    \value InternalAuto
           API elements that QDoc has automatically determined to be internal.
           Like \c Internal, corresponds to the \c{showinternal} configuration
           option/command line flag.
 
    \sa InclusionFlags, InclusionPolicy
*/
 
/*!
    \typedef InclusionFlags
    \relates InclusionFlag
    \headerfile inclusionflags.h
    \inmodule QDoc
 
    QFlags type for combining multiple InclusionFlag values.
*/
 
/*!
    \struct InclusionPolicy
    \headerfile inclusionpolicy.h
    \inmodule QDoc
    \brief Configuration-driven policy for including private API in documentation.
 
    InclusionPolicy captures the current configuration settings for private API
    documentation. It is constructed from QDoc's configuration variables and
    provides a consistent interface for inclusion decisions.
 
    The policy is typically created once per documentation run from the current
    configuration and passed to InclusionFilter for making inclusion decisions.
 
    \sa Config::createInclusionPolicy(), InclusionFilter
*/
 
/*!
    \variable InclusionPolicy::includePrivateFunction
    \brief Whether to include private functions in documentation.
 
    When true, private functions and methods are included in documentation
    output. Corresponds to the \c{includeprivate.functions} configuration
    variable. Takes precedence over the general includePrivate setting for
    function nodes.
*/
 
/*!
    \variable InclusionPolicy::includePrivateType
    \brief Whether to include private types in documentation.
 
    When true, private classes, enums, and typedefs are included in
    documentation output. Corresponds to the \c{includeprivate.types}
    configuration variable. Takes precedence over the general includePrivate
    setting for type nodes.
*/
 
/*!
    \variable InclusionPolicy::includePrivateVariable
    \brief Whether to include private variables in documentation.
 
    When true, private member variables and properties are included in
    documentation output. Corresponds to the \c{includeprivate.variables}
    configuration variable. Takes precedence over the general includePrivate
    setting for variable nodes.
*/
 
/*!
    \variable InclusionPolicy::showInternal
    \brief Whether to include internal API elements in documentation.
 
    When true, API elements marked with \\internal comments are included in
    documentation output. Corresponds to the \c{showinternal} configuration
    variable and the \c{--show-internal} command line option.
*/
 
/*!
    \fn InclusionFlags InclusionPolicy::toFlags() const
    \brief Converts the policy settings to flags for efficient comparison.
 
    Returns an InclusionFlags value representing which categories of private
    API should be included based on the current policy settings.
*/
 
/*!
    \struct NodeContext
    \headerfile nodecontext.h
    \inmodule QDoc
    \brief Lightweight capture of node state for inclusion decisions.
 
    NodeContext is a value type that captures relevant node properties once,
    avoiding repeated type checks and casts when evaluating inclusion rules.
    It is created from a Node via Node::createContext() and used by
    InclusionFilter to make inclusion decisions.
 
    The context captures:
    \list
    \li The node's type (function, class, variable, etc.)
    \li Whether the node has private access
    \li Whether the node is explicitly marked as \internal
    \li Whether the node is automatically determined to be internal
    \li Whether the node is a pure virtual function
    \endlist
 
    This approach eliminates redundant RTTI operations that were previously
    performed at each inclusion check point.
 
    \sa Node::createContext(), InclusionFilter
*/
 
/*!
    \variable NodeContext::type
    \brief The type of the documentation node.
 
    Stores the NodeType enum value, indicating whether this is a function,
    class, variable, or other type of documentation node.
*/
 
/*!
    \variable NodeContext::metaness
    \brief Stores the kind of function the node represents.
 
    Valid if \l type is NodeType::Function, \c std::nullopt
    otherwise.
*/
 
/*!
    \variable NodeContext::isPrivate
    \brief Whether the node has private access level.
 
    True if the node represents a private member of a class or a non-public
    API element.
*/
 
/*!
    \variable NodeContext::isInternal
    \brief Whether the node is explicitly marked as internal API.
 
    True if the node is marked with \\internal documentation command,
    indicating it's internal API not intended for public consumption.
*/
 
/*!
    \variable NodeContext::isInternalAuto
    \brief Whether the node is automatically determined to be internal.
 
    True if the node is automatically marked as internal, for example,
    because it is undocumented.
*/
 
/*!
    \variable NodeContext::isPureVirtual
    \brief Whether the node is a pure virtual function.
 
    Pure virtual functions require special handling as they must always be
    documented when included, since derived classes must implement them.
*/
 
/*!
    \fn InclusionFlags NodeContext::toFlags() const
    \brief Converts node properties to flags for policy matching.
 
    Returns an InclusionFlags value representing the categories this node
    belongs to. For non-private nodes, returns an empty flag set. For
    private nodes, returns flags indicating what specific type of
    private element it is (function, type, or variable).
*/
 
/*!
    \class InclusionFilter
    \headerfile inclusionfilter.h
    \inmodule QDoc
    \brief Centralized logic for documentation inclusion decisions.
 
    InclusionFilter provides static methods that implement the logic for
    determining whether a documentation node should be included in output
    or whether warnings should be generated for undocumented nodes.
 
    All inclusion decisions flow through this class, ensuring consistent
    behavior across different output generators and eliminating duplicate
    logic that was previously scattered throughout QDoc.
 
    \sa InclusionPolicy, NodeContext
*/
 
/*!
    \fn bool InclusionFilter::isIncluded(const InclusionPolicy& policy, const NodeContext& context)
    \brief Determines if a node should be included in documentation output.
 
    Returns true if the node described by \a context should be included
    in documentation according to the given \a policy.
 
    The method handles several special cases:
    \list
    \li Signals and slots are included (unless explicitly marked internal)
    \li Internal nodes are only included when showInternal policy is enabled
    \li Non-private nodes are always included (unless internal and showInternal is false)
    \li Pure virtual functions are always included (even if private, unless internal and showInternal is false)
    \li Private nodes are included based on policy flags
    \endlist
*/
 
/*!
    \fn bool InclusionFilter::requiresDocumentation(const InclusionPolicy& policy, const NodeContext& context)
    \brief Determines if warnings should be generated for undocumented nodes.
 
    Returns true if QDoc should warn about the node described by \a context
    being undocumented, according to the given \a policy.
 
    Generally follows the same rules as isIncluded(), but is used specifically
    for determining when to generate warnings about missing documentation.
*/
 
/*!
    \fn bool InclusionFilter::isPubliclyVisible(const InclusionPolicy& policy, const NodeContext& context)
    \brief Determines if a node should be visible in public documentation.
 
    Returns true if the node described by \a context should be considered
    publicly visible according to the given \a policy. This method implements
    the business rule: "Include everything except internal nodes when
    showInternal is disabled."
 
    This is primarily used by index file generation and cross-referencing
    systems that need to include private members for completeness but should
    respect the internal visibility policy.
 
    Unlike isIncluded(), this method only checks internal status and ignores
    private member inclusion policies, making it suitable for systems that
    need to preserve private API information for cross-referencing while
    still respecting internal API visibility rules.
 
    \sa isIncluded(), processInternalDocs()
*/
 
/*!
    \fn bool InclusionFilter::processInternalDocs(const InclusionPolicy& policy)
    \brief Determines if internal documentation should be processed.
 
    Returns true if the given \a policy indicates that internal documentation
    should be processed. This method implements the business rule: "Process
    internal documentation only when showInternal is enabled."
 
    This method is used by parsers, warning systems, and other components
    that need to make decisions based solely on the internal documentation
    policy without requiring a specific node context.
 
    \sa isPubliclyVisible(), isIncluded()
*/
 
/*!
    \fn bool InclusionFilter::isReimplementedMemberVisible(const InclusionPolicy& policy, const NodeContext& context)
    \brief Determines if a reimplemented member should appear in documentation.
 
    Returns true if the reimplemented member described by \a context should be
    documented according to the given \a policy. This method implements the
    business rule: "Reimplemented members are documented based on their access
    level in the derived class, not their internal status."
 
    This is specifically used for populating "Reimplemented Functions" sections,
    where the fact that a function overrides a base class method is architectural
    information that should be visible regardless of whether the implementation
    details are marked as internal.
 
    Unlike isIncluded(), this method treats internal status as orthogonal to
    reimplementation visibility - a public override of an internal base class
    function should still appear in the reimplemented functions list.
 
    The method handles several cases:
    \list
    \li Public and protected reimplemented members are always visible
    \li Pure virtual reimplemented members are always visible (even if private)
    \li Private reimplemented members follow private inclusion policies
    \li Internal status is explicitly ignored for reimplemented member visibility
    \endlist
 
    \sa isIncluded(), isPubliclyVisible(), requiresDocumentation()
*/