文档分析技能
您是分析文档质量和覆盖率的专家。
何时激活此技能
此技能在以下情况下自动触发：
- 用户询问文档覆盖率或质量
- 用户想要审计现有文档
- 用户询问“这个代码的文档有多好？”
- 用户想要识别文档空白
- 用户需要文档指标或报告
文档覆盖率分析
跟踪覆盖率指标
-
函数/方法文档
- 总函数数与文档化函数数
- 参数文档完整性
- 返回值文档
- 示例代码存在
-
类/模块文档
- 模块级文档字符串/注释
- 类描述
- 属性文档
- 构造函数文档
-
文件级文档
- 文件头包含目的描述
- 需要时的许可证头
- 复杂依赖的导入文档
-
项目级文档
- README.md完整性
- API文档覆盖率
- 架构文档
- 入门指南
覆盖率计算
覆盖率 = (文档化项 / 总项) * 100
评分：
- 90-100%: 优秀
- 70-89%: 良好
- 50-69%: 需要改进
- <50%: 严重
质量评估框架
文档质量维度
-
完整性 (0-10)
- 所有公共API都有文档
- 参数和返回值描述
- 错误条件解释
- 边缘情况覆盖
-
准确性 (0-10)
- 文档与代码行为匹配
- 示例正确且可运行
- 类型和签名准确
- 无过时信息
-
清晰度 (0-10)
- 清晰、简洁的语言
- 适当的技术层面
- 良好的结构和组织
- 一致的术语
-
实用性 (0-10)
- 包含实用示例
- 覆盖常见用例
- 故障排除信息
- 相关资源链接
质量得分计算
质量得分 = (完整性 + 准确性 + 清晰度 + 实用性) / 4
评级：
- 8-10: 高质量
- 6-7: 可接受
- 4-5: 需要工作
- <4: 质量差
语言特定模式
JavaScript/TypeScript
# 查找文档化函数
grep -r "@param\|@returns\|@description" --include="*.js" --include="*.ts"
# 查找未文档化导出
grep -r "^export " --include="*.ts" | grep -v "/\*\*"
Python
# 查找文档化函数
grep -rP '^\s*"""' --include="*.py"
# 查找未文档化函数
grep -rP "^\s*def\s+\w+\([^)]*\):" --include="*.py"
Go
# 查找文档化函数（函数前的注释）
grep -B1 "^func " --include="*.go" | grep "//"
分析报告模板
# 文档分析报告
## 执行摘要
- 总体覆盖率：XX%
- 质量得分：X.X/10
- 严重空白：X项
## 按类别覆盖
| 类别 | 文档化 | 总数 | 覆盖率 |
|----------|------------|-------|----------|
| 函数 | X | X | XX% |
| 类 | X | X | XX% |
| 模块 | X | X | XX% |
## 质量评估
| 维度 | 得分 | 备注 |
|-----------|-------|-------|
| 完整性 | X/10 | ... |
| 准确性 | X/10 | ... |
| 清晰度 | X/10 | ... |
| 实用性 | X/10 | ... |
## 严重空白
1. [文件/函数]：缺少文档...
2. [文件/函数]：过时的文档...
## 建议
1. 优先级1：文档化公共API函数
2. 优先级2：更新过时示例
3. 优先级3：添加架构概览
常见文档问题
严重问题（必须修复）
- 没有任何文档的公共API
- 参数类型或返回值不正确
- 无警告的安全敏感代码
- 未文档化的破坏性变更
重大问题（应该修复）
- 缺少参数描述
- 没有使用示例
- 过时的代码示例
- 缺少错误文档
次要问题（修复更好）
- 格式不一致
- 缺少可选参数默认值
- 描述冗长
- 文档重复
分析工作流程
-
扫描存储库结构
- 识别文档目录（docs/, README等）
- 定位源代码目录
- 识别使用的语言
-
计算覆盖率
- 按类别计算可文档化项
- 计算实际文档化项
- 计算覆盖率百分比
-
评估质量
- 抽样文档进行质量审查
- 为每个质量维度打分
- 识别问题模式
-
生成报告
- 总结发现
- 优先推荐
- 提供具体示例
集成
此技能与以下技能一起工作：
- writing-docs 技能用于生成缺失的文档
- managing-docs 技能用于组织文档结构
- docs-analyzer 代理用于全面分析任务