跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

writing-xml-doc-comments

Write or review C# XML documentation comments on public API surface. USE FOR: adding or reviewing XML documentation on public types, members, parameters, type parameters, and return values. DO NOT USE FOR: ordinary code comments (use csharp-style), or prose, markdown, README, and wiki text; those follow the writing standard.

Nice3point · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add Nice3point/revit-skills --skill writing-xml-doc-comments

技能说明


name: writing-xml-doc-comments description: > Write or review C# XML documentation comments on public API surface. USE FOR: adding or reviewing XML documentation on public types, members, parameters, type parameters, and return values. DO NOT USE FOR: ordinary code comments (use csharp-style), or prose, markdown, README, and wiki text; those follow the writing standard. license: MIT

Writing XML Doc Comments

Write reference documentation to an enterprise production standard, not tutorial or learning material. Document the contract a caller depends on, not the mechanics a reader can see in the signature. The conventions match Microsoft's own guidance for writing .NET API reference comments: complete, correct, contextual, and polished. Every tag opens with a third-person singular verb, has no personal pronoun, and states a contract instead of a mechanism.

When to use

  • Adding a public or protected type, member, or contract to a library or a shared assembly.
  • Reviewing XML documentation for coverage, tag order, opening phrasing, and contract accuracy.
  • Closing documentation gaps reported by CS1591 or CS1573.

Rules

  • Give every public and protected type, member, parameter, type parameter, and return value its tag.
  • Put the text on its own line between the opening and closing tag, indented four spaces past the /// marker; use the one-line form for a single short clause.
  • Indent a nested tag one level further, and indent a <code> block to the level its rendered output needs.
  • Write one sentence per tag and end it with a period; move a second sentence to <remarks>.
  • Ignore the line length; the text of a tag occupies one line however long it runs, and no line is wrapped by hand.
  • State the contract; never restate the name or the parameter list in words.
  • Describe observable behavior, not the current implementation.
  • Describe the member as it stands, not the change that produced it. The caller reading the documentation has no previous version to compare against.
  • State facts in the present indicative; never argue why.
  • Never use a personal pronoun (you, we, I); state the fact about the member instead.
  • Cut every purpose, result, cause, or comparison clause (so, that makes, which makes, because, rather than); if the clause states a fact the reader needs, make it its own sentence.

Tag order

Write the tags in this order.

  1. <summary>
  2. <value> — a property whose default or unit the caller needs
  3. <typeparam> — one per type parameter, in declaration order
  4. <param> — one per parameter, in declaration order
  5. <returns>
  6. <exception> — one per contract throw
  7. <remarks>
  8. <example>

Summary opening by member kind

The skeleton is identical for every declaration; the opening phrase is what changes.

DeclarationSummary opens withExample
Class, struct, recordRepresents …, Provides …, Defines …Represents the host portion of a URI.
Static class with extensionsExtension methods for …, Provides extension methods for …Provides extension methods for <see cref="IEndpointRouteBuilder" /> to add endpoints.
InterfaceDefines a contract that …, Provides an interface for …Defines a contract that represents the result of an HTTP endpoint.
AttributeSpecifies …Specifies a collection of tags in <see cref="Endpoint.Metadata" />.
Exception typeRepresents … errorRepresents an HTTP request error.
DelegateA function that …, A delegate that …A function that can process an HTTP request.
EnumDetermines …, Indicates whether …Determines how cookie security properties are set.
Enum memberthe effect of selecting the valueOpts out of compression over HTTPS.
Constant, static readonly fieldthe meaning of the valueHTTP status code 201.
ConstructorInitializes a new instance of the <see cref="T" /> class.—
Read-only propertyGets …Gets the HTTP status code for this exception.
Read-write propertyGets or sets …Gets or sets the prefix used to identify the current object.
Boolean propertyGets a value indicating whether …—
EventAn event that fires when …, An event that is raised when …An event that is raised when a field value changes.
Factory method`Creates a <see cref="T
阅读完整来源 ↗