Validation Engine

How boringdocs validates your documentation against your codebase.

Architecture

The validation engine works in three phases:

1. Parse — boringdocs parses your code (AST) and your docs (markdown, OpenAPI, etc.) into a unified representation.
2. Map — It builds a mapping between code constructs and their documentation entries.
3. Check — It runs validation rules against the map, reporting mismatches.

Code Parsing

boringdocs uses tree-sitter to parse source code into ASTs. It extracts:

• Function signatures (name, parameters, return types)
• Class definitions and methods
• API endpoints (Express routes, FastAPI decorators, etc.)
• Type definitions and interfaces
• Export declarations

Doc Parsing

Documentation is parsed based on format:

Markdown

Headings become section anchors. Code blocks are matched to language. Frontmatter provides metadata.

OpenAPI / Swagger

Parsed as structured data. Paths, schemas, and parameters are extracted directly.

JSDoc / TSDoc

Tags like @param, @returns, @example are extracted and matched to code constructs.

Mapping

The mapper links code constructs to doc entries using:

• Name matching — function getUser() maps to doc section "getUser"
• Path matching — endpoint GET /users/:id maps to doc path /users/{id}
• Proximity — inline doc comments map to the following code construct
• Explicit links — @see tags and cross-references

Rule Engine

Validation rules are declarative. Each rule has:

• A scope — what it applies to (endpoints, functions, types)
• A condition — what to check
• A severity — error, warning, or info
• A message — human-readable description of the issue

Built-in Rules

Rule	Description	Severity
endpoint-must-have-description	Every API endpoint must have a description	error
response-schema-must-match	Response schema in docs must match actual return type	error
no-orphaned-docs	Every doc section must map to a code construct	warning
no-orphaned-code	Every public function/endpoint must have documentation	warning
example-must-compile	Code examples in docs must be syntactically valid	error
param-must-match	Documented parameters must match function signature	error