AgentSkillsCN

api-docs

按照 .NET 指南，为 SkiaSharp 编写并审核 XML API 文档。 触发条件：“文档化类”、“添加 XML 文档”、“编写 XML 文档”、“添加三斜线注释”、“审核文档质量”、“检查文档是否存在错误”、“修复文档问题”、“补全缺失文档”、“移除‘待添加’占位符”以及 API 文档相关的需求。

SKILL.md
--- frontmatter
name: api-docs
description: >
  Write and review XML API documentation for SkiaSharp following .NET guidelines.
  
  Triggers: "document class", "add XML docs", "write XML documentation", "add triple-slash comments",
  "review documentation quality", "check docs for errors", "fix doc issues", "fill in missing docs",
  "remove To be added placeholders", API documentation requests.

API Documentation

Write and review XML API documentation for SkiaSharp.

File Locations

code
docs/SkiaSharpAPI/
├── SkiaSharp/              # Main namespace
│   ├── SKCanvas.xml        # One XML file per type
│   ├── SKPaint.xml
│   ├── SKImage.xml
│   └── ...
├── HarfBuzzSharp/          # HarfBuzz namespace
├── SkiaSharp.Views.*/      # Platform-specific views
└── index.xml               # Extension methods (auto-synced, don't edit)

Writing Documentation

  1. •Find the type's XML file in docs/SkiaSharpAPI/<Namespace>/<TypeName>.xml
  2. •Edit <summary>, <param>, <returns>, <value> tags within <Docs> sections
  3. •Follow patterns in references/patterns.md
  4. •After editing a file, validate XML syntax (see XML Validation below)
  5. •Run dotnet cake --target=docs-format-docs to validate and format

Reviewing Documentation

  1. •Search for issues using grep patterns below
  2. •Classify by severity using references/checklist.md
  3. •Fix issues following references/patterns.md
  4. •Run dotnet cake --target=docs-format-docs to validate

Quick Issue Search

bash
# Find placeholders
grep -r "To be added" docs/SkiaSharpAPI/

# Find empty tags (self-closing)
grep -rE "<(summary|value|returns)\s*/>" docs/SkiaSharpAPI/

# Find empty tags (open/close with optional whitespace)
grep -rE "<(summary|value|returns)>\s*</" docs/SkiaSharpAPI/

# Find spelling errors (common ones)
grep -riE "teh|recieve|seperate|occured|paramter" docs/SkiaSharpAPI/

# Find whitespace issues
grep -rE " </|  </" docs/SkiaSharpAPI/

Resources

XML Validation

CRITICAL: After completing all edits to an XML file, validate its XML syntax before moving to the next file.

Validation Command

bash
# Validate a single file
xmllint --noout docs/SkiaSharpAPI/SkiaSharp/SKCanvas.xml

# Validate all XML files in a namespace
find docs/SkiaSharpAPI/SkiaSharp -name "*.xml" -exec xmllint --noout {} \;

# Validate entire docs directory
find docs/SkiaSharpAPI -name "*.xml" -exec xmllint --noout {} \;

Common XML Errors to Avoid

  1. •Duplicate closing tags: </param></param> - happens when copy/pasting
  2. •Mismatched tags: <summary>...</param> - tag names must match
  3. •Unescaped characters: <, >, & must be &lt;, &gt;, &amp;
  4. •Missing closing tags: <summary>text without </summary>

Workflow

  1. •Make all edits to a file
  2. •Run xmllint --noout <file> to validate
  3. •If errors, fix them before proceeding
  4. •Move to next file