mcpField
C
code-documentation

code-documentation

github.com/aj-geddes开发375496 次安装35 周前更新
代码仓库

关于 code-documentation

面向开发者的代码文档编写技能，涵盖函数、类、API 和类型，并采用各语言惯例。内容强调示例、准确细节与可维护的注释。

主要功能

  1. 01JSDoc、文档字符串与 JavaDoc 指引
  2. 02函数和类文档
  3. 03API 与类型文档
  4. 04示例、参数和返回值说明

适用场景

  1. 01编写公开函数和类的文档
  2. 02从代码创建 API 文档
  3. 03添加用法示例和错误说明

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/aj-geddes/useful-ai-prompts --skill code-documentation

安装后在 Claude Code 中输入/code-documentation确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
class-documentation-2.md
class-documentation.md
function-documentation-2.md
function-documentation.md
module-documentation.md
type-definitions.md
templates/
doc-template.md

详细介绍

代码文档

目录

概述

使用 JSDoc、Python 文档字符串、JavaDoc 和内联注释等特定语言标准，创建清晰、全面的代码文档。

适用场景

  • 函数和类文档
  • JavaScript/TypeScript 的 JSDoc
  • Python 文档字符串
  • Java 的 JavaDoc
  • 内联代码注释
  • 根据代码生成 API 文档
  • 类型定义
  • 代码中的用法示例

快速开始

最小可运行示例：

/**
 * Calculates the total price including tax and discount.
 *
 * @param {number} basePrice - The base price before tax and discount
 * @param {number} taxRate - Tax rate as a decimal (e.g., 0.08 for 8%)
 * @param {number} [discount=0] - Optional discount amount
 * @returns {number} The final price after tax and discount
 * @throws {Error} If basePrice or taxRate is negative
 *
 * @example
 * const price = calculateTotalPrice(100, 0.08, 10);
 * console.log(price); // 98
 *
 * @example
 * // Without discount
 * const price = calculateTotalPrice(100, 0.08);
 * console.log(price); // 108
 */
function calculateTotalPrice(basePrice, taxRate, discount = 0) {
  if (basePrice < 0 || taxRate < 0) {
    throw new Error("Price and tax rate must be non-negative");
  }
  return basePrice * (1 + taxRate) - discount;
}

// ... (see reference guides for full implementation)

参考指南

references/ 目录中的详细实现：

指南内容
函数文档函数文档
类文档类文档
类型定义类型定义
函数文档函数文档
类文档类文档
模块文档模块文档

最佳实践

✅ 应该做
  • 彻底记录公共 API
  • 包含用法示例
  • 记录参数和返回值
  • 指明抛出的异常/错误
  • 使用特定语言的标准（JSDoc、文档字符串等）
  • 保持注释与代码同步更新
  • 说明“为什么”，而非“是什么”
  • 包含边界情况和注意事项
  • 添加相关函数的链接
  • 记录类型定义
  • 使用一致的格式
❌ 不应该做
  • 在注释中陈述显而易见的内容
  • 留下已注释掉的代码
  • 编写误导性注释
  • 不为复杂函数提供示例
  • 使用含糊的参数说明
  • 代码变更时忘记更新文档
  • 为简单代码添加过多注释

评论

支持 Markdown