Doc-Code Sync

The core mechanism that keeps your documentation in sync with your codebase.

Overview

Doc-Code Sync is boringdocs' core feature. It maintains a live, bidirectional mapping between your code constructs and their documentation entries. When either side changes, the sync detects it.

Sync Model

boringdocs uses a code-first sync model:

• Code is the source of truth for what exists
• Docs are the source of truth for what it means
• The sync layer ensures they stay aligned

What Gets Synced

Code Construct	Doc Element
API Endpoint	Path documentation + parameters
Function / Method	Function description + params + returns
Class	Class overview + constructor
Type / Interface	Type definition + field descriptions
Enum	Enum values + descriptions
Module / File	Module-level documentation

Sync States

Each mapping has a sync state:

synced

Code and docs agree. No action needed.

drifted

Code changed but docs haven't been updated (or vice versa).

missing-doc

Code exists but has no corresponding documentation.

missing-code

Documentation exists but the code it describes is gone.

conflict

Both code and docs changed in incompatible ways.

Auto-Sync

boringdocs can automatically update documentation stubs when code changes:

sync:
  auto_fix: true
  update_descriptions: false  # don't overwrite human-written descriptions
  add_missing_stubs: true     # create stubs for undocumented code
  remove_orphans: false       # don't delete orphaned docs automatically

Incremental Sync

On large codebases, boringdocs only re-parses files that changed since the last run. This keeps validation fast even on projects with thousands of files.