From febd4c492500a494c06b848dc6eb6bc3518f83a9 Mon Sep 17 00:00:00 2001
From: Genevieve Warren <24882762+gewarren@users.noreply.github.com>
Date: Tue, 30 Sep 2025 19:01:30 -0700
Subject: [PATCH] Expand C# documentation best practices (#273)

* Expand C# documentation best practices

* Update prompts/csharp-docs.prompt.md

* Apply suggestion from @Copilot

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Aaron Powell <me@aaron-powell.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 prompts/csharp-docs.prompt.md | 55 +++++++++++++++++++++++++++++------
 1 file changed, 46 insertions(+), 9 deletions(-)

diff --git a/prompts/csharp-docs.prompt.md b/prompts/csharp-docs.prompt.md
index 2ede7b3..2308fa7 100644
--- a/prompts/csharp-docs.prompt.md
+++ b/prompts/csharp-docs.prompt.md
@@ -8,19 +8,56 @@ description: 'Ensure that C# types are documented with XML comments and follow b
 
 - Public members should be documented with XML comments.
 - It is encouraged to document internal members as well, especially if they are complex or not self-explanatory.
-- Use `<summary>` for method descriptions. This should be a brief overview of what the method does.
-- Use `<param>` for method parameters.
-- Use `<paramref>` to reference parameters in documentation.
-- Use `<returns>` for method return values.
+
+## Guidance for all APIs
+
+- 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.
 - Use `<remarks>` for additional information, which can include implementation details, usage notes, or any other relevant context.
-- Use `<example>` for usage examples on how to use the member.
-- Use `<exception>` to document exceptions thrown by methods.
 - Use `<see langword>` for language-specific keywords like `null`, `true`, `false`, `int`, `bool`, etc.
+- Use `<c>` for inline code snippets.
+- Use `<example>` for usage examples on how to use the member.
+  - 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">`.
 - Use `<see cref>` to reference other types or members inline (in a sentence).
 - Use `<seealso>` for standalone (not in a sentence) references to other types or members in the "See also" section of the online docs.
 - Use `<inheritdoc/>` to inherit documentation from base classes or interfaces.
   - Unless there is major behavior change, in which case you should document the differences.
-- Use `<typeparam>` for type parameters in generic types or methods.
+
+## Methods
+
+- Use `<param>` to describe method parameters.
+  - The description should be a noun phrase that doesn't specify the data type.
+  - Begin with an introductory article.
+  - If the parameter is a flag enum, start the description with "A bitwise combination of the enumeration values that specifies...".
+  - If the parameter is a non-flag enum, start the description with "One of the enumeration values that specifies...".
+  - If the parameter is a Boolean, the wording should be of the form "`<see langword="true" />` to ...; otherwise, `<see langword="false" />`.".
+  - 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.".
+- Use `<paramref>` to reference parameter names in documentation.
+- Use `<typeparam>` to describe type parameters in generic types or methods.
 - Use `<typeparamref>` to reference type parameters in documentation.
-- Use `<c>` for inline code snippets.
-- 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">`.
+- Use `<returns>` to describe what the method returns.
+  - The description should be a noun phrase that doesn't specify the data type.
+  - Begin with an introductory article.
+  - If the return type is Boolean, the wording should be of the form "`<see langword="true" />` if ...; otherwise, `<see langword="false" />`.".
+
+## Constructors
+
+- The summary wording should be "Initializes a new instance of the <Class> class [or struct].".
+
+## Properties
+
+- The `<summary>` should start with:
+  - "Gets or sets..." for a read-write property.
+  - "Gets..." for a read-only property.
+  - "Gets [or sets] a value that indicates whether..." for properties that return a Boolean value.
+- Use `<value>` to describe the value of the property.
+  - The description should be a noun phrase that doesn't specify the data type.
+  - If the property has a default value, add it in a separate sentence, for example, "The default is `<see langword="false" />`".
+  - If the value type is Boolean, the wording should be of the form "`<see langword="true" />` if ...; otherwise, `<see langword="false" />`. The default is ...".
+
+## Exceptions
+
+- Use `<exception cref>` to document exceptions thrown by constructors, properties, indexers, methods, operators, and events.
+- Document all exceptions thrown directly by the member.
+- For exceptions thrown by nested members, document only the exceptions users are most likely to encounter.
+- The description of the exception describes the condition under which it's thrown.
+  - 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."