lmiranda
b5d36865ee
Add single-line visual headers to 66 command files across 10 plugins: - clarity-assist (2 commands): 💬 - claude-config-maintainer (5 commands): ⚙️ - cmdb-assistant (11 commands): 🖥️ - code-sentinel (3 commands): 🔒 - contract-validator (5 commands): ✅ - data-platform (10 commands): 📊 - doc-guardian (5 commands): 📝 - git-flow (8 commands): 🔀 - pr-review (7 commands): 🔍 - viz-platform (10 commands): 🎨 Each command now displays a consistent header at execution start: ┌────────────────────────────────────────────────────────────────┐ │ [icon] PLUGIN-NAME · Command Description │ └────────────────────────────────────────────────────────────────┘ Addresses #275 (other plugin commands visual output) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
141 lines
3.8 KiB
Markdown
141 lines
3.8 KiB
Markdown
---
|
|
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:
|
|
```bash
|
|
# 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 (/** */) |
|