azure-sdk-for-rust: Skill for Claude Code

Review public API doc comments

Write precise, standalone reference documentation for developers using the public API. Prioritize human understanding while keeping comments easy for LLMs to interpret. Explain what the API does, when to use it, and what callers must know. Avoid marketing, conversation, keyword stuffing, and unnecessary detail.

When to use

Use this skill when writing or revising public API documentation. Also use it when reviewing changes to public signatures, types, fields, variants, behavior, errors, panics, or feature availability, even if no doc comments changed.

Review workflow

1. Identify the affected public surface, including re-exports and observable behavior changed by private implementation. Stay within the requested scope.
2. Read each affected API's complete documentation and relevant implementation, tests, and surrounding type or module docs. Include ///, //!, and documentation attributes.
3. Apply every criterion below. Verify claims against code; do not invent guarantees, errors, panics, or safety requirements.
4. For reviews, report findings without editing. When asked to fix docs, preserve meaning and make focused edits. Never edit generated/; report the issue and route it to the TypeSpec specification or generator.
5. Validate relevant links and examples when possible. State what was checked and any limitations; never assume code compiles.

Review criteria

1. Apply Microsoft style to reference documentation

Apply these guidelines directly:

1. Express ideas simply. Remove needless words and complexity without losing required constraints or qualifications.
2. Use natural language. Prefer familiar words and direct sentences. Explain necessary domain terms and avoid unexplained jargon.
3. Be approachable. Use contractions when natural and unambiguous, but avoid banter and forced familiarity.
4. Lead with the useful fact. Start with the API's purpose or behavior. Surface important requirements and caller actions early.
5. Include enough, not everything. Keep details needed to choose and use the API; remove repetition, filler, and cryptic compression.
6. Use sentence case. Preserve proper names and exact Rust identifier casing.
7. Punctuate by context. Punctuate sentences, not headings. Keep list punctuation consistent.
8. Use serial commas. Include the comma before the final conjunction in lists of three or more items.
9. Use conventional spacing. Use one space after sentences and colons, no spaces around em dashes, and preserve meaningful Markdown formatting.
10. Write directly. Prefer active voice and meaningful verbs. Remove openings such as "You can" and "There is". Use natural summaries such as "Returns", "Creates", or "Deletes" where appropriate.