Back to Details

tasks-documentation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Skill Variant: Use this skill for autonomous documentation generation with structured templates. For interactive documentation tasks with user feedback, use 
documentation
instead.
技能变体： 此技能适用于使用结构化模板的自主文档生成。对于需要用户反馈的交互式文档任务，请改用
documentation
。

Documentation Workflow

文档工作流

Summary

概述

Goal: Autonomously generate or update code documentation (XML docs, JSDoc, API docs, architecture docs) following platform conventions.
  • Code Comments: XML docs for C# public APIs, JSDoc for TypeScript, inline for complex logic
  • API Documentation: Endpoint descriptions, request/response schemas, error codes
  • Architecture Documentation: Component diagrams, data flow, integration guides
  • Comment Types: 
    /// <summary>
    for APIs, 
    // TODO:
    for planned work, 
    // HACK:
    for workarounds
Key Principles:
  • Explain "why" not "what" -- never state the obvious
  • Keep documentation close to code, update when code changes
  • Use this skill for autonomous generation; use 
    documentation
    for interactive tasks
目标： 遵循平台约定，自主生成或更新代码文档（XML文档、JSDoc、API文档、架构文档）。
  • 代码注释： C#公共API使用XML文档，TypeScript使用JSDoc，复杂逻辑使用内联注释
  • API文档： 端点描述、请求/响应 schema、错误代码
  • 架构文档： 组件图、数据流、集成指南
  • 注释类型： 公共API使用
    /// <summary>
    ，计划工作使用
    // TODO:
    ，临时解决方案使用
    // HACK:
核心原则：
  • 解释“为什么”而非“是什么”——切勿陈述显而易见的内容
  • 保持文档与代码紧密关联，代码变更时同步更新文档
  • 此技能用于自主生成；交互式任务请使用
    documentation

When to Use This Skill

何时使用此技能

  • Creating API documentation
  • Writing code comments
  • Updating README files
  • Generating architecture documentation
  • 创建API文档
  • 编写代码注释
  • 更新README文件
  • 生成架构文档

Documentation Types

文档类型

1. Code Comments

1. 代码注释

  • XML docs for public APIs
  • Inline comments for complex logic
  • TODO/FIXME for technical debt
  • 公共API使用XML文档
  • 复杂逻辑使用内联注释
  • 技术债务使用TODO/FIXME

2. API Documentation

2. API文档

  • Endpoint descriptions
  • Request/response schemas
  • Error codes and handling
  • 端点描述
  • 请求/响应 schema
  • 错误代码与处理方式

3. Architecture Documentation

3. 架构文档

  • Component diagrams
  • Data flow documentation
  • Integration guides
  • 组件图
  • 数据流文档
  • 集成指南

Pattern 1: C# XML Documentation

模式1：C# XML文档

csharp
/// <summary>
/// Saves or updates an employee entity.
/// </summary>
/// <remarks>
/// This command handles both create and update operations.
/// For new employees, the Id should be null or empty.
/// </remarks>
public sealed class SaveEmployeeCommand : PlatformCqrsCommand<SaveEmployeeCommandResult>
{
    /// <summary>
    /// The unique identifier of the employee.
    /// Null or empty for new employees.
    /// </summary>
    public string? Id { get; set; }

    /// <summary>
    /// The employee's full name.
    /// </summary>
    /// <value>Must be non-empty and max 200 characters.</value>
    public string Name { get; set; } = string.Empty;
}
csharp
/// <summary>
/// Saves or updates an employee entity.
/// </summary>
/// <remarks>
/// This command handles both create and update operations.
/// For new employees, the Id should be null or empty.
/// </remarks>
public sealed class SaveEmployeeCommand : PlatformCqrsCommand<SaveEmployeeCommandResult>
{
    /// <summary>
    /// The unique identifier of the employee.
    /// Null or empty for new employees.
    /// </summary>
    public string? Id { get; set; }

    /// <summary>
    /// The employee's full name.
    /// </summary>
    /// <value>Must be non-empty and max 200 characters.</value>
    public string Name { get; set; } = string.Empty;
}

Pattern 2: TypeScript JSDoc

模式2：TypeScript JSDoc

typescript
/**
 * Manages the feature list state and operations.
 *
 * @example
 * ```typescript
 * @Component({ providers: [FeatureListStore] })
 * export class FeatureListComponent {
 *   constructor(private store: FeatureListStore) {
 *     store.loadItems();
 *   }
 * }
 * ```
 */
@Injectable()
export class FeatureListStore extends PlatformVmStore<FeatureListState> {
  /**
   * Loads items from the API with current filters.
   * Use `isLoading$('loadItems')` to check loading status.
   */
  public loadItems = this.effectSimple(() => /* ... */);
}
typescript
/**
 * Manages the feature list state and operations.
 *
 * @example
 * ```typescript
 * @Component({ providers: [FeatureListStore] })
 * export class FeatureListComponent {
 *   constructor(private store: FeatureListStore) {
 *     store.loadItems();
 *   }
 * }
 * ```
 */
@Injectable()
export class FeatureListStore extends PlatformVmStore<FeatureListState> {
  /**
   * Loads items from the API with current filters.
   * Use `isLoading$('loadItems')` to check loading status.
   */
  public loadItems = this.effectSimple(() => /* ... */);
}

Pattern 3: API Endpoint Documentation

模式3：API端点文档

csharp
/// <summary>
/// Employee management endpoints.
/// </summary>
[ApiController]
[Route("api/[controller]")]
[PlatformAuthorize]
public class EmployeeController : PlatformBaseController
{
    /// <summary>
    /// Retrieves a paginated list of employees.
    /// </summary>
    /// <response code="200">Returns the employee list.</response>
    /// <response code="401">Unauthorized.</response>
    [HttpGet]
    [ProducesResponseType(typeof(GetEmployeeListQueryResult), StatusCodes.Status200OK)]
    public async Task<IActionResult> GetList([FromQuery] GetEmployeeListQuery query)
        => Ok(await Cqrs.SendAsync(query));
}
csharp
/// <summary>
/// Employee management endpoints.
/// </summary>
[ApiController]
[Route("api/[controller]")]
[PlatformAuthorize]
public class EmployeeController : PlatformBaseController
{
    /// <summary>
    /// Retrieves a paginated list of employees.
    /// </summary>
    /// <response code="200">Returns the employee list.</response>
    /// <response code="401">Unauthorized.</response>
    [HttpGet]
    [ProducesResponseType(typeof(GetEmployeeListQueryResult), StatusCodes.Status200OK)]
    public async Task<IActionResult> GetList([FromQuery] GetEmployeeListQuery query)
        => Ok(await Cqrs.SendAsync(query));
}

Documentation Guidelines

文档指南

DO

建议

  • Document public APIs with XML/JSDoc
  • Explain "why" not "what"
  • Include usage examples
  • Keep documentation close to code
  • Update docs when code changes
  • 使用XML/JSDoc记录公共API
  • 解释“为什么”而非“是什么”
  • 包含使用示例
  • 保持文档与代码紧密关联
  • 代码变更时更新文档

DON'T

不建议

  • State the obvious
  • Leave TODO comments indefinitely
  • Write documentation that duplicates code
  • Create separate docs that become stale
  • 陈述显而易见的内容
  • 无限期保留TODO注释
  • 编写重复代码的文档
  • 创建会过时的独立文档

Comment Types

注释类型

TypeWhen to Use
/// <summary>
Public API documentation
// Explanation
Complex logic explanation
// TODO:
Planned improvements
// FIXME:
Known issues
// HACK:
Temporary workarounds
// NOTE:
Important information
类型使用场景
/// <summary>
公共API文档
// Explanation
复杂逻辑解释
// TODO:
计划改进项
// FIXME:
已知问题
// HACK:
临时解决方案
// NOTE:
重要信息

Verification Checklist

验证检查清单

  • Public APIs have XML/JSDoc documentation
  • Complex logic has explanatory comments
  • Examples are provided where helpful
  • Documentation is accurate and up-to-date
  • No obvious/redundant comments
  • TODO/FIXME items are actionable
IMPORTANT Task Planning Notes (MUST FOLLOW)
  • Always plan and break work into many small todo tasks
  • Always add a final review todo task to verify work quality and identify fixes/enhancements
  • 公共API已添加XML/JSDoc文档
  • 复杂逻辑已添加解释性注释
  • 必要处提供了使用示例
  • 文档准确且最新
  • 无明显/冗余注释
  • TODO/FIXME项具备可操作性
重要任务规划说明（必须遵守）
  • 始终规划并将工作拆分为多个小型待办任务
  • 始终添加最终审核待办任务，以验证工作质量并确定需要修复/增强的内容