..
    ----------------------------------------------------------------------------------------------
     Copyright (c) The Einsums Developers. All rights reserved.
     Licensed under the MIT License. See LICENSE.txt in the project root for license information.
    ----------------------------------------------------------------------------------------------


.. _cppapi_Visitor:

=======
Visitor
=======

.. note::
   Generated from the C++ headers by ``apiary --emit-cpp-docs-json``.

.. cpp:namespace:: apiary

.. cpp:class:: Visitor

   Walks a translation unit and builds a Module IR populated only with declarations carrying at least one APIARY_* annotation. Other declarations are ignored entirely.

   .. note::

      Class scope is tracked via a stack so that methods, fields, and nested
      types attach to the right BoundClass. Templates are detected and the
      is_template flag is set, but full instantiation handling is deferred to
      Phase 4.


   .. cpp:function:: Visitor(clang::ASTContext &ctx)

      Construct a Visitor bound to the given AST context.

      :param ctx: The Clang AST context to walk.


   .. cpp:function:: void set_module_header_filter(const std::vector<std::string> &headers)

      Set the list of source-include header paths (as passed via ``--source-include`` on the codegen command line).

      When non-empty, the visitor only binds declarations whose source
      location resolves to a file ending in one of these relative paths —
      transitive includes from other modules' headers are skipped to avoid
      duplicate bindings (the owning module's codegen run handles them).

      :param headers: The relative header paths to filter declarations by.


   .. cpp:function:: Module take()

      Move the built Module IR out of the visitor.

      :returns: The accumulated Module IR.


   .. cpp:function:: int error_count()

      Number of errors encountered during traversal.

      :returns: The error count.


   .. cpp:function:: int undocumented_count()

      Number of distinct undocumented public entities seen this run (only meaningful when ``set_report_undocumented(true)``).

      :returns: The count of distinct undocumented public entities.


   .. cpp:function:: bool TraverseCXXRecordDecl(clang::CXXRecordDecl *decl)

      Traverse a class-like record, pushing/popping the scope stack around the recursive descent into its members.

      :param decl: The record declaration being traversed.
      :returns: True to continue traversal.


   .. cpp:function:: bool TraverseClassTemplateDecl(clang::ClassTemplateDecl *decl)

      Traverse a class template, pushing/popping the scope stack around the recursive descent into its members.

      :param decl: The class template declaration being traversed.
      :returns: True to continue traversal.


   .. cpp:function:: bool TraverseNamespaceDecl(clang::NamespaceDecl *decl)

      Traverse a namespace, pushing/popping the inherited submodule directive stack.

      Entities inside a ``namespace APIARY_MODULE("foo") bar { ... }`` block
      inherit ``module:foo`` unless they declare their own override.

      :param decl: The namespace declaration being traversed.
      :returns: True to continue traversal.


   .. cpp:function:: bool VisitCXXMethodDecl(clang::CXXMethodDecl *decl)

      Visit a C++ method declaration and produce an IR record.

      :param decl: The method declaration being visited.
      :returns: True to continue traversal.


   .. cpp:function:: bool VisitFunctionDecl(clang::FunctionDecl *decl)

      Visit a free function declaration and produce an IR record.

      :param decl: The function declaration being visited.
      :returns: True to continue traversal.


   .. cpp:function:: bool VisitFieldDecl(clang::FieldDecl *decl)

      Visit a field declaration and produce an IR record.

      :param decl: The field declaration being visited.
      :returns: True to continue traversal.


   .. cpp:function:: bool VisitEnumDecl(clang::EnumDecl *decl)

      Visit an enum declaration and produce an IR record.

      :param decl: The enum declaration being visited.
      :returns: True to continue traversal.


   .. cpp:function:: bool VisitTypedefNameDecl(clang::TypedefNameDecl *decl)

      Visit a typedef/using-alias declaration (docs mode only).

      :param decl: The typedef-name declaration being visited.
      :returns: True to continue traversal.


   .. cpp:function:: bool VisitConceptDecl(clang::ConceptDecl *decl)

      Visit a C++20 concept declaration (docs mode only).

      :param decl: The concept declaration being visited.
      :returns: True to continue traversal.