Visitor

Note

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

class Visitor : public clang::RecursiveASTVisitor<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.

explicit Visitor(clang::ASTContext &ctx)

Construct a Visitor bound to the given AST context.

Parameters:

ctx – The Clang AST context to walk.

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

Parameters:

headers – The relative header paths to filter declarations by.

void set_report_undocumented_references(bool on)

Enable “report undocumented references” mode (docs mode only).

When on, every namespace-scope class, enum, or concept that a documented declaration names in its signature (return and parameter types, non-type template parameter types, type constraints, public bases, public field types) but that is itself undocumented is printed to stderr as file:line:col: undocumented <kind> '<name>' referenced by '<entity>'. Such a reference has no declaration to resolve to in the reference, so a nitpicky Sphinx build fails on it. Each referenced entity is reported once per process. Types from system headers and from std, detail, impl, and anonymous namespaces are never reported, and neither are typedefs, which docs mode declares whether or not they are documented.

Parameters:

on – Whether to enable report-undocumented-references mode.

int undocumented_reference_count() const

Number of distinct undocumented entities referenced from documented signatures this run (only meaningful when set_report_undocumented_references(true)).

Returns:

The count of distinct undocumented referenced entities.

Module take() &&

Move the built Module IR out of the visitor.

Returns:

The accumulated Module IR.

int error_count() const

Number of errors encountered during traversal.

Returns:

The error count.

int undocumented_count() const

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

Returns:

The count of distinct undocumented public entities.

int annotated_seen() const

Number of APIARY_*-annotated declarations seen anywhere in the translation unit, before the module-header filter is applied.

Paired with annotated_filtered_out() this separates the two ways a run can legitimately produce nothing, which are otherwise indistinguishable in the output: the parse saw no annotations at all (wrong header, or the annotation macros expanded to nothing), versus it saw them and the header filter rejected every one (a --source-include that does not match where the declarations actually live).

Returns:

The count of annotated declarations encountered.

int annotated_filtered_out() const

Number of annotated declarations rejected by the module-header filter. See annotated_seen() for why this is tracked separately.

Returns:

The count of annotated declarations the filter rejected.

bool TraverseCXXRecordDecl(clang::CXXRecordDecl *decl)

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

Parameters:

decl – The record declaration being traversed.

Returns:

True to continue traversal.

bool TraverseClassTemplateDecl(clang::ClassTemplateDecl *decl)

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

Parameters:

decl – The class template declaration being traversed.

Returns:

True to continue traversal.

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.

Parameters:

decl – The namespace declaration being traversed.

Returns:

True to continue traversal.

bool VisitCXXMethodDecl(clang::CXXMethodDecl *decl)

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

Parameters:

decl – The method declaration being visited.

Returns:

True to continue traversal.

bool VisitFunctionDecl(clang::FunctionDecl *decl)

Visit a free function declaration and produce an IR record.

Parameters:

decl – The function declaration being visited.

Returns:

True to continue traversal.

bool VisitFieldDecl(clang::FieldDecl *decl)

Visit a field declaration and produce an IR record.

Parameters:

decl – The field declaration being visited.

Returns:

True to continue traversal.

bool VisitEnumDecl(clang::EnumDecl *decl)

Visit an enum declaration and produce an IR record.

Parameters:

decl – The enum declaration being visited.

Returns:

True to continue traversal.

bool VisitTypedefNameDecl(clang::TypedefNameDecl *decl)

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

Parameters:

decl – The typedef-name declaration being visited.

Returns:

True to continue traversal.

bool VisitConceptDecl(clang::ConceptDecl *decl)

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

Parameters:

decl – The concept declaration being visited.

Returns:

True to continue traversal.

bool VisitVarDecl(clang::VarDecl *decl)

Visit a namespace-scope variable declaration (docs mode only).

Parameters:

decl – The variable declaration being visited.

Returns:

True to continue traversal.