鱼皮AI导航
鱼皮AI导航
  • 主页
  • 社区
  • AI工具
  • AI知识库
  • AI提示词
  • MCP
  • Skills
  • AI学习资源
  • AI资讯
  • GitHub开源
登录/注册

code-documentation

生成清晰的代码文档,涵盖 API 说明、项目结构和架构决策,通过示例代码与注释帮助开发者理解实现逻辑,确保技术信息准确且易于维护。

效率工具文档处理软件开发
访问 GitHub
文档Skills.MD
name
code-documentation
description
Writing effective code documentation - API docs, README files, inline comments, and technical guides. Use for documenting codebases, APIs, or writing developer guides.
source
wshobson/agents
license
MIT

Code Documentation

README Structure

Standard README Template

▼
markdown
复制代码
# Project Name Brief description of what this project does. ## Quick Start \`\`\`bash npm install npm run dev \`\`\` ## Installation Detailed installation instructions... ## Usage \`\`\`typescript import { something } from 'project'; // Example usage const result = something.doThing(); \`\`\` ## API Reference ### `functionName(param: Type): ReturnType` Description of what the function does. **Parameters:** - `param` - Description of parameter **Returns:** Description of return value **Example:** \`\`\`typescript const result = functionName('value'); \`\`\` ## Configuration | Option | Type | Default | Description | |--------|------|---------|-------------| | `option1` | `string` | `'default'` | What it does | ## Contributing How to contribute... ## License MIT

API Documentation

JSDoc/TSDoc Style

▼
typescript
复制代码
/** * Creates a new user account. * * @param userData - The user data for account creation * @param options - Optional configuration * @returns The created user object * @throws {ValidationError} If email is invalid * @example * ```ts * const user = await createUser({ * email: 'user@example.com', * name: 'John' * }); * ``` */ async function createUser( userData: UserInput, options?: CreateOptions ): Promise<User> { // Implementation } /** * Configuration options for the API client. */ interface ClientConfig { /** The API base URL */ baseUrl: string; /** Request timeout in milliseconds @default 5000 */ timeout?: number; /** Custom headers to include in requests */ headers?: Record<string, string>; }

OpenAPI/Swagger

▼
yaml
复制代码
openapi: 3.0.0 info: title: My API version: 1.0.0 paths: /users: post: summary: Create a user description: Creates a new user account requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UserInput' responses: '201': description: User created successfully content: application/json: schema: $ref: '#/components/schemas/User' '400': description: Invalid input components: schemas: UserInput: type: object required: - email - name properties: email: type: string format: email name: type: string User: type: object properties: id: type: string email: type: string name: type: string createdAt: type: string format: date-time

Inline Comments

When to Comment

▼
typescript
复制代码
// GOOD: Explain WHY, not WHAT // Use binary search because the list is always sorted and // can contain millions of items - O(log n) vs O(n) const index = binarySearch(items, target); // GOOD: Explain complex business logic // Users get 20% discount if they've been members for 2+ years // AND have made 10+ purchases (per marketing team decision Q4 2024) if (user.memberYears >= 2 && user.purchaseCount >= 10) { applyDiscount(0.2); } // GOOD: Document workarounds // HACK: Safari doesn't support this API, fallback to polling // TODO: Remove when Safari adds support (tracking: webkit.org/b/12345) if (!window.IntersectionObserver) { startPolling(); }

When NOT to Comment

▼
typescript
复制代码
// BAD: Stating the obvious // Increment counter by 1 counter++; // BAD: Explaining clear code // Check if user is admin if (user.role === 'admin') { ... } // BAD: Outdated comments (worse than no comment) // Returns the user's full name <-- Actually returns email now! function getUserIdentifier(user) { return user.email; }

Architecture Documentation

ADR (Architecture Decision Record)

▼
markdown
复制代码
# ADR-001: Use PostgreSQL for Primary Database ## Status Accepted ## Context We need a database for storing user data and transactions. Options considered: PostgreSQL, MySQL, MongoDB, DynamoDB. ## Decision Use PostgreSQL with Supabase hosting. ## Rationale - Strong ACID compliance needed for financial data - Team has PostgreSQL experience - Supabase provides auth and realtime features - pgvector extension for future AI features ## Consequences - Need to manage schema migrations - May need read replicas for scale - Team needs to learn Supabase-specific features

Component Documentation

▼
markdown
复制代码
## Authentication Module ### Overview Handles user authentication using JWT tokens with refresh rotation. ### Flow 1. User submits credentials to `/auth/login` 2. Server validates and returns access + refresh tokens 3. Access token used for API requests (15min expiry) 4. Refresh token used to get new access token (7d expiry) ### Dependencies - `jsonwebtoken` - Token generation/validation - `bcrypt` - Password hashing - `redis` - Refresh token storage ### Configuration - `JWT_SECRET` - Secret for signing tokens - `ACCESS_TOKEN_EXPIRY` - Access token lifetime - `REFRESH_TOKEN_EXPIRY` - Refresh token lifetime

Documentation Principles

  1. Write for your audience - New devs vs API consumers
  2. Keep it close to code - Docs in same repo, near relevant code
  3. Update with code - Stale docs are worse than none
  4. Examples over explanations - Show, don't just tell
  5. Progressive disclosure - Quick start first, details later
效率工具
文档处理
软件开发

快捷安装

复制到终端去安装 Skill

npxadd-skillskillcreatorai/Ai-Agent-Skills--skill"code-documentation"
站长:程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
站长:程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
🔥热门工具
朱雀AI检测朱雀AI检测
朱雀AI检测助手朱雀AI检测助手
LovartLovart
老鱼简历老鱼简历
WritePass官网WritePass官网
面多多面多多
CursorCursor
星月写作星月写作
朱雀AI检测助手朱雀AI检测助手
零感AI零感AI
Skills 推荐
debug
debug 是一个系统化定位软件缺陷根因的技能,适用于用户报告 'fix'、'broken'、'error' 等问题或测试意外失败时。它通过可验证的假设、最小复现、因果链分析和回归测试,确保在修复前准确定位根本原因。
retrieving-developer-knowledge
retrieving-developer-knowledge 用于搜索、获取和整合 Google 官方开发者文档,覆盖 Google Cloud、AI/Gemini、Android、Chrome、Web、Flutter、Go、Firebase 等平台,适用于查询 gcloud CLI 命令、API 语法、IAM 权限或架构对比等场景。
diff-intake
diff-intake 读取 PR 或分支差异,生成结构化 YAML 变更摘要,用于下游 analytics instrumentation 技能。适用于用户提交 PR 链接、分支对比或原始 diff 后需理解变更内容、评估分析覆盖或启动埋点流程的场景。
webapp-testing
提供本地 Web 应用的端到端测试能力,支持页面导航、元素交互、表单填写、动态等待、断言验证、截图捕获、浏览器日志收集及网络请求拦截,适用于前端功能验证与 UI 行为调试。
definition-of-done-generator
自动生成项目完成标准的规范定义与配置文件,提供符合企业级工作流要求的最佳实践指导,输出可直接投入生产环境的代码和验证结果,适用于需要标准化流程审批、合规审查及跨系统集成的复杂项目管理场景。