--- name: csharp-docs description: "Use when adding or reviewing XML documentation comments on C# public APIs: summary, param, returns, exception, inheritdoc, remarks, and example conventions." --- # C# XML documentation Every public type and member carries an XML doc comment. Internal and private members get comments only for what the code cannot say (`csharp-standards`). ## Tags - ``: one sentence, starting with a present-tense, third-person verb. - ``: implementation details, usage notes, other context. - `` for keywords (`null`, `true`, `false`, `int`); `` for inline code. - `` with `` inside it for usage examples. - `` for references in a sentence; `` for standalone "See also" references. - `` / `` / `` for parameters and type parameters. - `` to inherit from a base class or interface — unless the behavior changes materially; then document the difference. - `` for every exception the member throws directly, and only the likely ones from nested calls. State the condition directly ("The order was not found."), never "Thrown if…". ## Wording | Element | Wording | | --- | --- | | `` | Noun phrase with an article, no data type | | ``, flag enum | "A bitwise combination of the enumeration values that specifies…" | | ``, other enum | "One of the enumeration values that specifies…" | | `` / ``, Boolean | "`` to … (or if …); otherwise, ``." | | ``, `out` | "When this method returns, contains …. This parameter is treated as uninitialized." | | `` | Noun phrase with an article, no data type | | Constructor `` | "Initializes a new instance of the `` class [or struct]." | | Primary constructor | No separate block: one `` per parameter on the type's comment, after its `` | | Property `` | "Gets or sets…" (read-write), "Gets…" (read-only), "Gets [or sets] a value that indicates whether…" (Boolean) | | Property `` | Noun phrase, no data type; default in its own sentence: "The default is ``." Boolean: "`` if …; otherwise, ``. The default is …" |