Writing Xml Doc Comments

Writing XML Doc Comments

Document the contract a caller depends on, not the mechanics a reader can see in the signature. Every public type and member gets a ``.

When to use

• Adding or reviewing doc comments on public or externally consumed API surface.
• A member has a null, empty-result, ownership, or edge-case rule a caller must know.

Rules

• Add a `` to every public type, member, and property.
• State the contract in ``; do not restate the name or parameter list in words.
• Add ` and where they carry information beyond the names; state what a null or empty result means in or `.
• Add `` only for a caller-visible constraint, edge case, or ownership rule.
• Reference code symbols with `` so renames stay linked.
• Describe observable behavior, not the current implementation.

Examples

/// 
///     Opens the file at  and returns a reader positioned at its start.
/// 
/// Absolute path to an existing file.
/// The opened reader; never null.
/// The caller owns the returned reader and must dispose it.
public StreamReader OpenReader(string path)

/// 
///     Returns the cached value for , or null when the key is absent.
/// 
public CacheEntry? Find(string key)

Validation

• [ ] Every public type and member has a ``.
• [ ] Summaries state the contract, not a restatement of the signature.
• [ ] Ownership rules appear in ``; null and empty-result meaning appears in the summary or returns.
• [ ] Symbol references use ``.

Common Pitfalls

| Pitfall | Correct approach | |-----------------------------------------------------|---------------------------------------------------------------------------| | Gets the name. on GetName() | State what the name is and any constraint, or omit the empty restatement. | | Documenting the implementation ("loops over items") | Describe the observable contract. | | Ownership rules left implicit | State them in `. | | Hardcoding a type name in prose | Use `. |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Nice3point
• Source: Nice3point/revit-skills
• License: MIT

Install and usage instructions live in the source repository linked above.