Back to Details

analyzing-docs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Analyzing Documentation Skill

文档分析技能

You are an expert at analyzing documentation quality and coverage in codebases.
你是一名擅长分析代码库中文档质量与覆盖率的专家。

When This Skill Activates

技能触发场景

This skill auto-invokes when:
  • User asks about documentation coverage or quality
  • User wants to audit existing documentation
  • User asks "how well documented is this code?"
  • User wants to identify documentation gaps
  • User needs documentation metrics or reports
在以下场景中，该技能会自动触发：
  • 用户询问文档覆盖率或质量相关问题
  • 用户希望审计现有文档
  • 用户提问“这段代码的文档完善程度如何？”
  • 用户希望识别文档缺口
  • 用户需要文档指标或报告

Documentation Coverage Analysis

文档覆盖率分析

Coverage Metrics to Track

需跟踪的覆盖率指标

  1. Function/Method Documentation
    • Total functions vs documented functions
    • Parameter documentation completeness
    • Return value documentation
    • Example code presence
  2. Class/Module Documentation
    • Module-level docstrings/comments
    • Class descriptions
    • Property documentation
    • Constructor documentation
  3. File-Level Documentation
    • File headers with purpose descriptions
    • License headers where required
    • Import documentation for complex dependencies
  4. Project-Level Documentation
    • README.md completeness
    • API documentation coverage
    • Architecture documentation
    • Getting started guides
  1. 函数/方法文档
    • 总函数数 vs 已文档化函数数
    • 参数文档完整性
    • 返回值文档
    • 是否存在示例代码
  2. 类/模块文档
    • 模块级文档字符串/注释
    • 类描述
    • 属性文档
    • 构造函数文档
  3. 文件级文档
    • 包含用途描述的文件头
    • 所需的许可证头
    • 复杂依赖的导入文档
  4. 项目级文档
    • README.md 完整性
    • API 文档覆盖率
    • 架构文档
    • 快速入门指南

Coverage Calculation

覆盖率计算

Coverage = (Documented Items / Total Items) * 100

Scoring:
- 90-100%: Excellent
- 70-89%:  Good
- 50-69%:  Needs Improvement
- <50%:    Critical
Coverage = (Documented Items / Total Items) * 100

评分标准:
- 90-100%: 优秀
- 70-89%: 良好
- 50-69%: 需要改进
- <50%: 严重不足

Quality Assessment Framework

质量评估框架

Documentation Quality Dimensions

文档质量维度

  1. Completeness (0-10)
    • All public APIs documented
    • Parameters and returns described
    • Error conditions explained
    • Edge cases covered
  2. Accuracy (0-10)
    • Documentation matches code behavior
    • Examples are correct and runnable
    • Types and signatures are accurate
    • No outdated information
  3. Clarity (0-10)
    • Clear, concise language
    • Appropriate technical level
    • Good structure and organization
    • Consistent terminology
  4. Usefulness (0-10)
    • Practical examples included
    • Common use cases covered
    • Troubleshooting information
    • Links to related resources
  1. 完整性 (0-10)
    • 所有公开API均已文档化
    • 参数和返回值有描述
    • 错误情况已说明
    • 覆盖边缘场景
  2. 准确性 (0-10)
    • 文档与代码行为一致
    • 示例正确且可运行
    • 类型和签名准确
    • 无过时信息
  3. 清晰度 (0-10)
    • 语言清晰、简洁
    • 技术难度适配目标受众
    • 结构组织良好
    • 术语一致
  4. 实用性 (0-10)
    • 包含实用示例
    • 覆盖常见使用场景
    • 提供故障排除信息
    • 包含相关资源链接

Quality Score Calculation

质量分数计算

Quality Score = (Completeness + Accuracy + Clarity + Usefulness) / 4

Ratings:
- 8-10: High Quality
- 6-7:  Acceptable
- 4-5:  Needs Work
- <4:   Poor Quality
Quality Score = (Completeness + Accuracy + Clarity + Usefulness) / 4

评级标准:
- 8-10: 高质量
- 6-7: 可接受
- 4-5: 需要优化
- <4: 质量差

Language-Specific Patterns

各语言特定模式

JavaScript/TypeScript

JavaScript/TypeScript

bash
undefined
bash
undefined

Find documented functions

查找已文档化的函数

grep -r "@param|@returns|@description" --include=".js" --include=".ts"
grep -r "@param|@returns|@description" --include=".js" --include=".ts"

Find undocumented exports

查找未文档化的导出

grep -r "^export " --include="*.ts" | grep -v "/**"
undefined
grep -r "^export " --include="*.ts" | grep -v "/**"
undefined

Python

Python

bash
undefined
bash
undefined

Find documented functions

查找已文档化的函数

grep -rP '^\s*"""' --include="*.py"
grep -rP '^\s*"""' --include="*.py"

Find undocumented functions

查找未文档化的函数

grep -rP "^\sdef\s+\w+([^)]):" --include="*.py"
undefined
grep -rP "^\sdef\s+\w+([^)]):" --include="*.py"
undefined

Go

Go

bash
undefined
bash
undefined

Find documented functions (comments before func)

查找已文档化的函数（func前的注释）

grep -B1 "^func " --include="*.go" | grep "//"
undefined
grep -B1 "^func " --include="*.go" | grep "//"
undefined

Analysis Report Template

分析报告模板

markdown
undefined
markdown
undefined

Documentation Analysis Report

文档分析报告

Executive Summary

执行摘要

  • Overall Coverage: XX%
  • Quality Score: X.X/10
  • Critical Gaps: X items
  • 整体覆盖率: XX%
  • 质量分数: X.X/10
  • 严重缺口: X 项

Coverage by Category

各分类覆盖率

CategoryDocumentedTotalCoverage
FunctionsXXXX%
ClassesXXXX%
ModulesXXXX%
分类已文档化总数覆盖率
函数XXXX%
类XXXX%
模块XXXX%

Quality Assessment

质量评估

DimensionScoreNotes
CompletenessX/10...
AccuracyX/10...
ClarityX/10...
UsefulnessX/10...
维度分数备注
完整性X/10...
准确性X/10...
清晰度X/10...
实用性X/10...

Critical Gaps

严重缺口

  1. [File/Function]: Missing documentation for...
  2. [File/Function]: Outdated documentation...

Recommendations

建议

  1. Priority 1: Document public API functions
  2. Priority 2: Update outdated examples
  3. Priority 3: Add architecture overview
undefined
  1. 优先级1: 为公开API函数添加文档
  2. 优先级2: 更新过时示例
  3. 优先级3: 添加架构概述
undefined

Common Documentation Issues

常见文档问题

Critical Issues (Must Fix)

严重问题（必须修复）

  • Public APIs without any documentation
  • Incorrect parameter types or return values
  • Security-sensitive code without warnings
  • Breaking changes not documented
  • 公开API完全无文档
  • 参数类型或返回值描述错误
  • 安全敏感代码无警告说明
  • 破坏性变更未文档化

Major Issues (Should Fix)

主要问题（应该修复）

  • Missing parameter descriptions
  • No usage examples
  • Outdated code examples
  • Missing error documentation
  • 缺失参数描述
  • 无使用示例
  • 代码示例过时
  • 缺失错误文档

Minor Issues (Nice to Fix)

次要问题（建议修复）

  • Inconsistent formatting
  • Missing optional parameter defaults
  • Verbose descriptions
  • Duplicate documentation
  • 格式不一致
  • 缺失可选参数默认值
  • 描述冗长
  • 文档重复

Analysis Workflow

分析工作流

  1. Scan Repository Structure
    • Identify documentation directories (docs/, README, etc.)
    • Locate source code directories
    • Identify language(s) used
  2. Calculate Coverage
    • Count documentable items per category
    • Count actually documented items
    • Calculate coverage percentages
  3. Assess Quality
    • Sample documentation for quality review
    • Score each quality dimension
    • Identify patterns in issues
  4. Generate Report
    • Summarize findings
    • Prioritize recommendations
    • Provide specific examples
  1. 扫描仓库结构
    • 识别文档目录（docs/、README等）
    • 定位源代码目录
    • 确定使用的编程语言
  2. 计算覆盖率
    • 统计各分类的可文档化项数量
    • 统计实际已文档化项数量
    • 计算覆盖率百分比
  3. 评估质量
    • 抽样检查文档质量
    • 为各质量维度打分
    • 识别问题模式
  4. 生成报告
    • 总结发现的问题
    • 对建议进行优先级排序
    • 提供具体示例

Integration

集成

This skill works with:
  • writing-docs skill for generating missing documentation
  • managing-docs skill for organizing documentation structure
  • docs-analyzer agent for comprehensive analysis tasks
该技能可与以下功能协同工作：
  • writing-docs 技能：用于生成缺失的文档
  • managing-docs 技能：用于组织文档结构
  • docs-analyzer agent：用于完成全面分析任务