leo-claude-mktplace/plugins/doc-guardian/commands/doc-coverage.md

description

description
Calculate documentation coverage percentage for functions and classes

Documentation Coverage

Analyze codebase to calculate documentation coverage metrics.

Visual Output

When executing this command, display the plugin header:

┌──────────────────────────────────────────────────────────────────┐
│  📝 DOC-GUARDIAN · Documentation Coverage                        │
└──────────────────────────────────────────────────────────────────┘

Then proceed with the analysis.

Process

1. Scan Source Files Identify all documentable items:

   Python:

   • Functions (def)
   • Classes
   • Methods
   • Module-level docstrings

   JavaScript/TypeScript:

   • Functions (function, arrow functions)
   • Classes
   • Methods
   • JSDoc comments

   Other Languages:

   • Adapt patterns for Go, Rust, etc.

2. Determine Documentation Status For each item, check:

   • Has docstring/JSDoc comment
   • Docstring is non-empty and meaningful (not just pass or TODO)
   • Parameters are documented (for detailed mode)
   • Return type is documented (for detailed mode)

3. Calculate Metrics

   Coverage = (Documented Items / Total Items) * 100
   

   Levels:

   • Basic: Item has any docstring
   • Standard: Docstring describes purpose
   • Complete: All parameters and return documented

4. Output Format

## Documentation Coverage Report

### Summary
- Total documentable items: 156
- Documented: 142
- Coverage: 91.0%

### By Type
| Type | Total | Documented | Coverage |
|------|-------|------------|----------|
| Functions | 89 | 85 | 95.5% |
| Classes | 23 | 21 | 91.3% |
| Methods | 44 | 36 | 81.8% |

### By Directory
| Path | Total | Documented | Coverage |
|------|-------|------------|----------|
| src/api/ | 34 | 32 | 94.1% |
| src/utils/ | 28 | 28 | 100.0% |
| src/models/ | 45 | 38 | 84.4% |
| tests/ | 49 | 44 | 89.8% |

### Undocumented Items
- [ ] src/api/handlers.py:45 `create_order()`
- [ ] src/api/handlers.py:78 `update_order()`
- [ ] src/models/user.py:23 `UserModel.validate()`

Options

Flag	Description	Default
--path <dir>	Scan specific directory	Project root
--exclude <glob>	Exclude files matching pattern	**/test_*,**/*_test.*
--include-private	Include private members (_prefixed)	false
--include-tests	Include test files	false
--min-coverage <pct>	Fail if below threshold	none
--format <fmt>	Output format (table, json, markdown)	table
--detailed	Check parameter/return docs	false

Thresholds

Common coverage targets:

Level	Coverage	Description
Minimal	60%	Basic documentation exists
Good	80%	Most public APIs documented
Excellent	95%	Comprehensive documentation

CI Integration

Use --min-coverage to enforce standards:

# Fail if coverage drops below 80%
claude /doc-coverage --min-coverage 80

Exit codes:

• 0: Coverage meets threshold (or no threshold set)
• 1: Coverage below threshold

Example Usage

/doc-coverage
/doc-coverage --path src/
/doc-coverage --min-coverage 85 --exclude "**/generated/**"
/doc-coverage --detailed --include-private

Language Detection

File extensions mapped to documentation patterns:

Extension	Language	Doc Format
.py	Python	Docstrings (""")
.js, .ts	JavaScript/TypeScript	JSDoc (/** */)
.go	Go	// comments above
.rs	Rust	/// doc comments
.rb	Ruby	# comments, YARD
.java	Java	Javadoc (/** */)