# Documentation Enforcement
**Status**: ✅ Production (v2.142.0)
**PMAT-7001**: Phase 3 (REFACTOR) Complete
## Overview
Documentation Enforcement is a quality gate system that automatically validates the quality of CLI help text and MCP tool documentation. It ensures all documentation is complete, accurate, and non-generic.
## Features
### Automated Validation
- **MCP Tool Documentation**: Validates all MCP tool descriptions and parameters
- **CLI Documentation**: Validates CLI command help text (via test suite)
- **Generic Detection**: Identifies placeholder/low-quality documentation
- **Parameter Validation**: Ensures all parameters have types, descriptions, and defaults
### Quality Gate Integration
- Integrated into PMAT's quality gate system
- Works alongside complexity, SATD, and dead code checks
- Configurable CLI/MCP validation flags
- Supports strict mode for build blocking
### JSON Reporting
- Export comprehensive validation reports
- Programmatic analysis for CI/CD integration
- Per-tool and per-parameter metrics
- Issue tracking with severity levels
### Pre-commit Hooks
- Automatic validation before commits
- Fast execution (<100ms)
- Clear error messages with remediation steps
- Configurable enforcement via environment variable
## Usage
### Command Line
```bash
# Run documentation enforcement via quality gate
pmat quality-gate --checks docs-enforcement
# Check MCP documentation only
pmat quality-gate --checks docs-enforcement --check-mcp
# Check both CLI and MCP
pmat quality-gate --checks docs-enforcement --check-cli --check-mcp
# Strict mode (fail build on violations)
pmat quality-gate --checks docs-enforcement --strict
```
### Programmatic API
#### Quality Gate Integration
```rust
use pmat::services::quality_gate_service::{
QualityCheck, QualityGateInput, QualityGateService
};
use pmat::services::service_base::Service;
use std::path::PathBuf;
#[tokio::main]
async fn main() -> anyhow::Result<()> {
let service = QualityGateService::new();
let input = QualityGateInput {
path: PathBuf::from("."),
checks: vec![QualityCheck::DocsEnforcement {
check_cli: false,
check_mcp: true,
}],
strict: false,
};
let output = service.process(input).await?;
println!("Passed: {}", output.passed);
println!("Total checks: {}", output.summary.total_checks);
println!("Violations: {}", output.summary.total_violations);
Ok(())
}
```
#### JSON Export
```rust
use pmat::docs_enforcement::mcp_checker::generate_validation_report_json;
fn main() -> anyhow::Result<()> {
let json = generate_validation_report_json()?;
println!("{}", json);
Ok(())
}
```
**JSON Output Structure**:
```json
{
"total_tools": 4,
"valid_tools": 4,
"invalid_tools": 0,
"total_issues": 0,
"tools": [
{
"tool_name": "scaffold_agent",
"has_description": true,
"description_length": 92,
"description_is_generic": false,
"has_input_schema": true,
"parameters": [
{
"name": "name",
"has_description": true,
"description": "Agent project name (lowercase, alphanumeric, hyphens only)",
"description_is_generic": false,
"has_type": true,
"param_type": "string",
"is_required": true,
"has_default": false,
"issues": []
}
],
"issues": []
}
]
}
```
### Pre-commit Hook
Enable documentation enforcement in your pre-commit hook:
```bash
# In .git/hooks/pre-commit or environment
export PMAT_DOCS_ENFORCEMENT_ENABLED=true
# Hook runs automatically on commit
git commit -m "Your changes"
```
**Manual Installation**:
```bash
# Install PMAT pre-commit hook
pmat hooks install
# Verify hook is active
pmat hooks status
```
## Validation Rules
### Tool Documentation
A valid tool must have:
- ✅ **Description**: Non-empty, >20 characters
- ✅ **Non-generic**: Not placeholder text (e.g., "A tool", "Helper function")
- ✅ **Input Schema**: Valid parameter schema defined
- ✅ **All Parameters**: Every parameter properly documented
### Parameter Documentation
A valid parameter must have:
- ✅ **Description**: Non-empty, >15 characters
- ✅ **Type**: Explicit type specification (string, number, boolean, array, object)
- ✅ **Required Status**: Clear indication if required or optional
- ✅ **Default Values**: Optional parameters document their defaults
- ✅ **Non-generic**: Meaningful description, not "The parameter" or "A value"
### Generic Detection
The system flags these as generic:
- "A tool/function/parameter that..."
- "Helper for..."
- "Utility to..."
- "The [name] parameter"
- Empty or very short descriptions (<15 chars)
## Configuration
### Quality Gate Configuration
```toml
# .pmat.toml or pmat.toml
[quality_gate]
docs_enforcement = { check_cli = true, check_mcp = true }
strict = false
```
### Pre-commit Hook Configuration
```bash
# Environment variables
export PMAT_DOCS_ENFORCEMENT_ENABLED=true # Enable/disable check
export PMAT_DOCS_CHECK_CLI=true # Check CLI docs
export PMAT_DOCS_CHECK_MCP=true # Check MCP docs
```
## CI/CD Integration
### GitHub Actions
```yaml
name: Documentation Quality
on: [push, pull_request]
jobs:
docs-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Install PMAT
run: cargo install pmat
- name: Check Documentation Quality
run: |
pmat quality-gate --checks docs-enforcement --strict --format json > docs-report.json
- name: Upload Report
uses: actions/upload-artifact@v3
with:
name: docs-report
path: docs-report.json
```
### GitLab CI
```yaml
docs-check:
stage: test
script:
- cargo install pmat
- pmat quality-gate --checks docs-enforcement --strict
artifacts:
reports:
junit: docs-report.xml
```
## Examples
### Check All MCP Tools
```bash
$ pmat quality-gate --checks docs-enforcement
✅ Documentation Enforcement (PMAT-7001)
MCP: checked, CLI: skipped
Results:
- scaffold_agent: ✅ 5 parameters, 0 issues
- validate_roadmap: ✅ 2 parameters, 0 issues
- health_check: ✅ 7 parameters, 0 issues
- generate_tickets: ✅ 3 parameters, 0 issues
Total: 4 tools, 17 parameters, 0 issues
```
### Strict Mode (Fail on Violations)
```bash
$ pmat quality-gate --checks docs-enforcement --strict
❌ Documentation Enforcement (PMAT-7001)
1 documentation issue found
Violations:
- MCP tool: my_tool
Error: Tool description too short (15 chars, min 20)
Exit code: 1
```
### JSON Output
```bash
{
"check": "Documentation Enforcement (PMAT-7001)",
"passed": true,
"message": "Documentation enforcement passed (MCP: checked, CLI: skipped)",
"violations": []
}
```
## Performance
| Pre-commit hook | <100ms | Fast enough for real-time feedback |
| Quality gate | ~5s | Full validation with all checks |
| JSON export | <10ms | Suitable for CI/CD pipelines |
| Test suite | <20ms | 6 comprehensive tests |
## Troubleshooting
### Common Issues
**Issue**: "Tool description is generic"
```
Error: Tool description is generic: 'A tool that processes data'
```
**Solution**: Provide specific description explaining what the tool does:
```rust
"Analyze code complexity using cyclomatic and cognitive metrics"
```
**Issue**: "Optional parameter should document default value"
```
Error: Optional parameter 'timeout' should document default value
```
**Solution**: Include default in description:
```rust
"Timeout in seconds (default: 30)"
```
**Issue**: "Parameter description too short"
```
Error: Parameter 'path' description too short (10 chars)
```
**Solution**: Provide detailed description (>15 chars):
```rust
"Path to project directory for analysis"
```
### Debug Mode
```bash
# Run tests with detailed output
cargo test --test docs_enforcement_unit_test -- --nocapture
# Check specific tool validation
pmat validate-docs --tool scaffold_agent --verbose
```
## Implementation Details
### Architecture
```
docs_enforcement/
├── generic_detector.rs # Generic text detection
├── mcp_checker.rs # MCP tool validation
└── cli_checker.rs # CLI documentation validation
services/
└── quality_gate_service.rs # Quality gate integration
```
### Test Coverage
- **Unit Tests**: 2 tests (validation logic, JSON export)
- **Integration Tests**: 4 tests (quality gate integration)
- **Total Coverage**: 6/6 tests passing (100%)
### Validation Flow
```
1. Load tool definitions
2. For each tool:
a. Validate description (length, generic check)
b. Validate input schema exists
c. For each parameter:
- Check description (length, generic)
- Check type specification
- Check default documentation (optional params)
3. Generate validation report
4. Return pass/fail with violations
```
## Related Features
- **[Quality Gates](../operations/quality-gates.md)** - Overall quality gate system
- **[Pre-commit Hooks](../operations/hooks.md)** - Hook configuration
- **[MCP Protocol](./mcp-protocol.md)** - MCP tool development
## Version History
- **v2.142.0** (2025-10-06): Phase 3 complete - Quality gate integration, JSON export, pre-commit hooks
- **v2.141.0** (2025-10-06): Phase 2 complete - MCP validation working
- **v2.140.0** (2025-10-05): Phase 1 complete - Test framework created
## References
- **Specification**: [CLI_MCP_DOCUMENTATION_ENFORCEMENT.md](../specifications/components/documentation.md)
- **Ticket**: [TICKET-PMAT-7001.md](../tickets/TICKET-PMAT-7001.md)
- **Phase 3 Results**: [PMAT-7001-REFACTOR-PHASE-RESULTS.md](../tickets/PMAT-7001-REFACTOR-PHASE-RESULTS.md)
- **Changelog**: [CHANGELOG.md](../../CHANGELOG.md)
## Contributing
When adding new MCP tools or CLI commands:
1. Provide detailed, specific descriptions (>20 chars for tools, >15 for params)
2. Avoid generic placeholders ("A tool that...", "Helper for...")
3. Document all parameter types explicitly
4. Document default values for optional parameters
5. Run `cargo test --test docs_enforcement_unit_test` before committing
## License
Part of PMAT - Licensed under MIT OR Apache-2.0