AGENT SKILL

doc-coverage

Detect missing documentation in code (XML docs, docstrings, JSDoc) and project files (CHANGELOG gaps). Produces coverage reports with specific gaps by file and symbol. Use for pre-PR validation, CI gates, or documentation audits.

License 许可
MIT
所属仓库
loriensleafs/brain
最近更新
2026-03-11
Stars
★ 0
Forks
0

01 前言 Front Matter

name
doc-coverage
model
claude-sonnet-4-5
agents
[ "qa", "implementer", "analyst" ]
license
MIT
metadata
{ "version": "1.0.0" }
description
Detect missing documentation in code (XML docs, docstrings, JSDoc) and project files (CHANGELOG gaps). Produces coverage reports with specific gaps by file and symbol. Use for pre-PR validation, CI gates, or documentation audits.

02 资源文件 140

03 SKILL.md 正文

Documentation Coverage

Detect missing documentation across code and project files with coverage metrics.

Triggers

  • check documentation coverage
  • find missing docs
  • validate API documentation
  • check XML doc comments
  • run doc coverage scan

Quick Start

# Check all files in current directory
bun run ${CLAUDE_SKILL_DIR}/scripts/check_docs.ts --target .

# Check only changed files (CI mode)
bun run ${CLAUDE_SKILL_DIR}/scripts/check_docs.ts --git-staged

# Check specific files
bun run ${CLAUDE_SKILL_DIR}/scripts/check_docs.ts src/models/user.cs src/services/auth.py

# JSON output for automation
bun run ${CLAUDE_SKILL_DIR}/scripts/check_docs.ts --target . --format json --output coverage.json

# Set minimum threshold
bun run ${CLAUDE_SKILL_DIR}/scripts/check_docs.ts --target . --min-coverage 80

Evidence

Created based on analysis of moq.analyzers closed PR reviewer patterns:

  • 8.9% of human reviewer feedback (10 of 112 comments) addressed documentation gaps
  • Common patterns: Missing XML doc comments, CHANGELOG not updated, undocumented public APIs
  • Examples: "Missing XML doc comments", "Update CHANGELOG.md", "Public API needs documentation"

Source: Analysis of closed PR reviewer patterns.


Documentation Types Checked

C# XML Documentation

Element Check Example
<summary> Required on public types, methods, properties /// <summary>Description</summary>
<param> Required for each parameter /// <param name="id">The ID</param>
<returns> Required for non-void methods /// <returns>Result description</returns>
<exception> Recommended for thrown exceptions /// <exception cref="ArgumentNullException">

Python Docstrings

Element Check Example
Module docstring Required at top of file """Module description."""
Function docstring Required for public functions """Function description."""
Class docstring Required for public classes """Class description."""
Args section Recommended (Google style) Args:\n param: Description

JavaScript/TypeScript JSDoc

Element Check Example
Function JSDoc Required for exported functions /** @description ... */
Class JSDoc Required for exported classes /** @class ... */
@param Required for each parameter @param {string} name
@returns Required for non-void functions @returns {number}

CHANGELOG Coverage

Check Description
Entry exists PRs with breaking changes have CHANGELOG entry
Version section Current version has section in CHANGELOG.md
Date format Entries follow consistent date format

When to Use

Use this skill when:

  • Preparing code for PR submission (catch documentation gaps before review)
  • Setting up CI gates for documentation quality
  • Auditing existing codebase documentation coverage
  • Enforcing documentation standards on public APIs

Use doc-sync instead when:

  • Syncing CLAUDE.md navigation files
  • Updating architecture documentation in README files
  • Not checking code-level documentation

Output Formats

Text (default)

Documentation Coverage Report
=============================

Overall Coverage: 73.2% (below 80% threshold)

Gaps Found: 12

src/services/auth.cs:45:AuthenticateUser
  - Missing: <summary> on public method
  - Missing: <param name="credentials">

src/models/user.py:12:User
  - Missing: class docstring

CHANGELOG.md
  - Missing: entry for breaking change in v2.1.0

JSON

{
  "coverage_percent": 73.2,
  "threshold": 80,
  "passed": false,
  "total_symbols": 156,
  "documented_symbols": 114,
  "gaps": [
    {
      "file": "src/services/auth.cs",
      "line": 45,
      "symbol": "AuthenticateUser",
      "type": "method",
      "missing": ["summary", "param:credentials"]
    }
  ]
}

Markdown

Produces a markdown report suitable for PR comments or documentation.


Configuration

Create .doccoveragerc.json in project root:

{
  "min_coverage_percent": 80,
  "check_public_only": true,
  "check_changelog": true,
  "exclude_patterns": [
    "**/tests/**",
    "**/test_*.py",
    "**/*.Tests.cs",
    "**/dist/**",
    "**/node_modules/**"
  ],
  "languages": {
    "csharp": {
      "require_summary": true,
      "require_param": true,
      "require_returns": true,
      "require_exception": false
    },
    "python": {
      "style": "google",
      "require_module_docstring": true,
      "require_args_section": false
    },
    "javascript": {
      "require_jsdoc": true,
      "require_param": true,
      "require_returns": true
    }
  }
}

Exit Codes

Code Meaning Action
0 Coverage meets threshold Proceed with PR
10 Coverage below threshold Add documentation
1 Error (file not found, parse error) Fix error

Integration

Pre-commit Hook

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: doc-coverage
        name: Documentation Coverage
        entry: bun run .claude/skills/doc-coverage/scripts/check_docs.ts --git-staged --min-coverage 80
        language: system
        pass_filenames: false

GitHub Actions

# .github/workflows/docs.yml
name: Documentation Coverage
on: [pull_request]

jobs:
  doc-coverage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Check documentation coverage
        run: |
          bun run .claude/skills/doc-coverage/scripts/check_docs.ts \
            --target . \
            --min-coverage 80 \
            --format json \
            --output coverage.json
      - name: Upload coverage report
        uses: actions/upload-artifact@v4
        with:
          name: doc-coverage
          path: coverage.json

Anti-Patterns

Avoid Why Instead
Requiring 100% coverage Leads to low-quality filler docs Set realistic threshold (80%)
Checking test files Test docs are less critical Exclude test patterns
Ignoring CHANGELOG Breaking changes need documentation Enable changelog checks
No configuration One size doesn't fit all Use .doccoveragerc.json

Verification

After running:

  • [ ] Coverage percentage reported
  • [ ] All gaps have file:line:symbol location
  • [ ] Exit code matches coverage status
  • [ ] Configuration file respected (if present)

Scripts

Script Purpose Exit Codes
scripts/check_docs.ts Main documentation coverage scanner 0=pass, 10=below threshold, 1=error

Extension Points

  1. New languages: Add parser in check_docs.ts for additional languages
  2. Custom checks: Add project-specific documentation requirements
  3. Report formats: Add SARIF or other CI-friendly formats
  4. Threshold by type: Different thresholds for classes vs methods

Related Skills

Skill Relationship
style-enforcement Complements with code style checks
code-qualities-assessment Broader quality assessment including docs
analyze Deep codebase analysis including doc patterns

04 同仓库更多 Skills

loriensleafs
loriensleafs/brain

validation-authority

Treat upstream validators as authoritative. Align local config to them. Use when validation fails unexpectedly, before modifying validator behavior, or when tempted to change upstream tool code.

★ 0
loriensleafs
loriensleafs/brain

using-brain-memory

Guidance for using Brain semantic memory effectively. Applies Zettelkasten atomic note principles with observations and relations. Use when deciding whether to query or create notes, structuring note content, or understanding the semantic knowledge graph.

★ 0
loriensleafs
loriensleafs/brain

threat-modeling

Structured security analysis using OWASP Four-Question Framework and STRIDE methodology. Generates threat matrices with risk ratings, mitigations, and prioritization. Use for attack surface analysis, security architecture review, or when asking what can go wrong.

★ 0
loriensleafs
loriensleafs/brain

taste-lints

Custom lints with agent-readable remediation instructions. Enforces taste invariants (file size, naming conventions, structured logging, complexity) and surfaces errors that agents can act on directly. Use when writing or reviewing code to catch style violations early.

Skill与智能体开发
★ 0
loriensleafs
loriensleafs/brain

style-enforcement

Validate code against style rules from .editorconfig, StyleCop.json, and Directory.Build.props. Detects line ending violations, naming convention issues, indentation problems, and charset mismatches across C#, Python, TypeScript, and JavaScript. Produces JSON reports for pre-commit hooks and CI pipelines.

★ 0
loriensleafs
loriensleafs/brain

steering-matcher

Match file paths against steering file glob patterns to determine applicable steering guidance. Use when orchestrator needs to inject context-aware guidance based on files being modified.

★ 0