|
| 1 | +--- |
| 2 | +agent: 'agent' |
| 3 | +tools: ['search/changes', 'search/codebase', 'edit/editFiles', 'read/problems'] |
| 4 | +description: 'Ensure that C# types are documented with XML comments and follow best practices for documentation.' |
| 5 | +--- |
| 6 | + |
| 7 | +# C# Documentation Best Practices |
| 8 | + |
| 9 | +- Public members should be documented with XML comments. |
| 10 | +- It is encouraged to document internal members as well, especially if they are complex or not self-explanatory. |
| 11 | + |
| 12 | +## Guidance for all APIs |
| 13 | + |
| 14 | +- Use `<summary>` to provide a brief, one sentence, description of what the type or member does. Start the summary with a present-tense, third-person verb. |
| 15 | +- Use `<remarks>` for additional information, which can include implementation details, usage notes, or any other relevant context. |
| 16 | +- Use `<see langword>` for language-specific keywords like `null`, `true`, `false`, `int`, `bool`, etc. |
| 17 | +- Use `<c>` for inline code snippets. |
| 18 | +- Use `<example>` for usage examples on how to use the member. |
| 19 | + - Use `<code>` for code blocks. `<code>` tags should be placed within an `<example>` tag. Add the language of the code example using the `language` attribute, for example, `<code language="csharp">`. |
| 20 | +- Use `<see cref>` to reference other types or members inline (in a sentence). |
| 21 | +- Use `<seealso>` for standalone (not in a sentence) references to other types or members in the "See also" section of the online docs. |
| 22 | +- Use `<inheritdoc/>` to inherit documentation from base classes or interfaces. |
| 23 | + - Unless there is major behavior change, in which case you should document the differences. |
| 24 | + |
| 25 | +## Methods |
| 26 | + |
| 27 | +- Use `<param>` to describe method parameters. |
| 28 | + - The description should be a noun phrase that doesn't specify the data type. |
| 29 | + - Begin with an introductory article. |
| 30 | + - If the parameter is a flag enum, start the description with "A bitwise combination of the enumeration values that specifies...". |
| 31 | + - If the parameter is a non-flag enum, start the description with "One of the enumeration values that specifies...". |
| 32 | + - If the parameter is a Boolean, the wording should be of the form "`<see langword="true" />` to ...; otherwise, `<see langword="false" />`.". |
| 33 | + - If the parameter is an "out" parameter, the wording should be of the form "When this method returns, contains .... This parameter is treated as uninitialized.". |
| 34 | +- Use `<paramref>` to reference parameter names in documentation. |
| 35 | +- Use `<typeparam>` to describe type parameters in generic types or methods. |
| 36 | +- Use `<typeparamref>` to reference type parameters in documentation. |
| 37 | +- Use `<returns>` to describe what the method returns. |
| 38 | + - The description should be a noun phrase that doesn't specify the data type. |
| 39 | + - Begin with an introductory article. |
| 40 | + - If the return type is Boolean, the wording should be of the form "`<see langword="true" />` if ...; otherwise, `<see langword="false" />`.". |
| 41 | + |
| 42 | +## Constructors |
| 43 | + |
| 44 | +- The summary wording should be "Initializes a new instance of the <Class> class [or struct].". |
| 45 | + |
| 46 | +## Properties |
| 47 | + |
| 48 | +- The `<summary>` should start with: |
| 49 | + - "Gets or sets..." for a read-write property. |
| 50 | + - "Gets..." for a read-only property. |
| 51 | + - "Gets [or sets] a value that indicates whether..." for properties that return a Boolean value. |
| 52 | +- Use `<value>` to describe the value of the property. |
| 53 | + - The description should be a noun phrase that doesn't specify the data type. |
| 54 | + - If the property has a default value, add it in a separate sentence, for example, "The default is `<see langword="false" />`". |
| 55 | + - If the value type is Boolean, the wording should be of the form "`<see langword="true" />` if ...; otherwise, `<see langword="false" />`. The default is ...". |
| 56 | + |
| 57 | +## Exceptions |
| 58 | + |
| 59 | +- Use `<exception cref>` to document exceptions thrown by constructors, properties, indexers, methods, operators, and events. |
| 60 | +- Document all exceptions thrown directly by the member. |
| 61 | +- For exceptions thrown by nested members, document only the exceptions users are most likely to encounter. |
| 62 | +- The description of the exception describes the condition under which it's thrown. |
| 63 | + - Omit "Thrown if ..." or "If ..." at the beginning of the sentence. Just state the condition directly, for example "An error occurred when accessing a Message Queuing API." |
0 commit comments