Add examples for XML on extension members (#50551)

* Add examples for XML on `extension`s

Fixes #49956

Add examples and explanations for writing documentation on `extension` nodes.

Include how the XML comments on the `extension` node for `<summary>`, `<param>` and `<typeparam>` are copied to all members of that extension block.

* forgot the XML tag

* Copilot style feedback.

* Apply suggestions from code review

Co-authored-by: Genevieve Warren <[email protected]>

* Respond to feedback.

---------

Co-authored-by: Genevieve Warren <[email protected]>

Author: BillWagner

docs/csharp/language-reference/keywords/extension.md

@@ -1,34 +1,37 @@
 ---
 title: "Extension member declarations"
 description: "Learn the syntax to declare extension members in C#. Extension members enable you to add functionality to types and interfaces in those instances where you don't have the source for the original type. Extensions are often paired with generic interfaces to implement a common set of functionality across all types that implement that interface."
-ms.date: 09/17/2025
+ms.date: 12/11/2025
 f1_keywords:
   - "extension_CSharpKeyword"
   - "extension"
 ---
 # Extension declaration (C# Reference)
 
-Beginning with C# 14, top level, nongeneric `static class` declarations can use `extension` blocks to declare *extension members*. Extension members are methods or properties and can appear to be instance or static members. Earlier versions of C# enable *extension methods* by adding `this` as a modifier to the first parameter of a static method declared in a top-level, nongeneric static class.
+Starting with C# 14, top-level, nongeneric `static class` declarations can use `extension` blocks to declare *extension members*. Extension members are methods or properties and can appear to be instance or static members. Earlier versions of C# enable *extension methods* by adding `this` as a modifier to the first parameter of a static method declared in a top-level, nongeneric static class.
 
 The `extension` block specifies the type and receiver for extension members. You can declare methods, properties, or operators inside the `extension` declaration. The following example declares a single extension block that defines an instance extension method, an instance property, and a static operator method.
 
+> [!NOTE]
+> All the examples in this article include XML comments for the members and the extension block. The node on the `extension` block describes the extended type and the receiver parameter. The C# compiler copies this node to the generated member for all members in the extension block. These examples demonstrate the preferred style for generating XML documentation for extension members.
+
 :::code language="csharp" source="./snippets/extensions.cs" id="ExtensionMembers":::
 
 The `extension` defines the receiver: `sequence`, which is an `IEnumerable<int>`. The receiver type can be nongeneric, an open generic, or a closed generic type. The name `sequence` is in scope in every instance member declared in that extension. The extension method and property both access `sequence`.
 
-Any of the extension members can be accessed as though they were members of the receiver type:
+You access any of the extension members as though they were members of the receiver type:
 
 :::code language="csharp" source="./snippets/extensions.cs" id="UseExtensionMethod":::
 
 You can declare any number of members in a single block, as long as they share the same receiver. You can declare as many extension blocks in a single class as well. Different extensions don't need to declare the same type or name of receiver. The extension parameter doesn't need to include the parameter name if the only members are static:
 
 :::code language="csharp" source="./snippets/extensions.cs" id="StaticExtensions":::
 
-Static extensions can be called as though they're static members of the receiver type:
+You call static extensions as though they're static members of the receiver type:
 
 :::code language="csharp" source="./snippets/extensions.cs" id="UseStaticExtensions":::
 
-Operators are called as though they're user defined operators on the type.
+You call operators as though they're user defined operators on the type.
 
 > [!IMPORTANT]  
 > An extension doesn't introduce a *scope* for member declarations. All members declared in a single class, even if in multiple extensions, must have unique signatures. The generated signature includes the receiver type in its name for static members and the receiver parameter for extension instance members.
@@ -37,18 +40,18 @@ The following example shows an extension method using the `this` modifier:
 
 :::code language="csharp" source="./snippets/ExtensionMethods.cs" id="ExtensionMethod":::
 
-The `Add` method can be called from any other method as though it was a member of the `IEnumerable<int>` interface:
+You can call the `Add` method from any other method as though it was a member of the `IEnumerable<int>` interface:
 
 :::code language="csharp" source="./snippets/ExtensionMethods.cs" id="UseExtensionMethod":::
 
 Both forms of extension methods generate the same intermediate language (IL). Callers can't make a distinction between them. In fact, you can convert existing extension methods to the new member syntax without a breaking change. The formats are both binary and source compatible.
 
 ## Generic extension blocks
 
-Where you specify the type parameters for an extension member declared in an extension block depends on where that type parameter is required:
+Where you specify the type parameters for an extension member declared in an extension block depends on where you need the type parameter:
 
-- You add the type parameter to the `extension` declaration when the type parameter is used in the receiver.
-- You add the type parameter to the member declaration when the type is distinct from any type parameter specified on the receiver.
+- Add the type parameter to the `extension` declaration when the type parameter is used in the receiver.
+- Add the type parameter to the member declaration when the type is distinct from any type parameter specified on the receiver.
 - You can't specify the same type parameter in both locations.
 
 The following example shows an extension block for `IEnumerable<T>` where two of the extension members require a second type parameter:

docs/csharp/language-reference/keywords/snippets/Extensions.cs

@@ -1,10 +1,24 @@
 namespace keywords;
 
 // <ExtensionMembers>
+/// <summary>
+/// Contains extension members for numeric sequences.
+/// </summary>
 public static class NumericSequences
 {
+    /// <summary>
+    /// Defines extensions for integer sequences.
+    /// </summary>
+    /// <param name="sequence">The sequence used as a receiver.</param>
     extension(IEnumerable<int> sequence)
     {
+        /// <summary>
+        /// Adds a scalar value to each element in the sequence.
+        /// </summary>
+        /// <param name="operand">The amount to add.</param>
+        /// <returns>
+        /// A new sequence where each value contains the updated value.
+        /// </returns>
         public IEnumerable<int> AddValue(int operand)
         {
             foreach (var item in sequence)
@@ -13,6 +27,12 @@ public IEnumerable<int> AddValue(int operand)
             }
         }
 
+        /// <summary>
+        /// Gets the median value of the sequence.
+        /// </summary>
+        /// <remarks>
+        /// This value is calculated when requested.
+        /// </remarks>
         public int Median
         {
             get
@@ -35,6 +55,16 @@ public int Median
             }
         }
 
+        /// <summary>
+        /// Concatenates two sequences of integers into a single sequence.
+        /// </summary>
+        /// <remarks>The resulting sequence enumerates all elements from <paramref name="left"/> in order,
+        /// followed by all elements from <paramref name="right"/>. Enumeration is deferred and performed lazily as the
+        /// returned sequence is iterated.</remarks>
+        /// <param name="left">The first sequence of integers to concatenate. Cannot be null.</param>
+        /// <param name="right">The second sequence of integers to concatenate. Cannot be null.</param>
+        /// <returns>A sequence that contains the elements of the first sequence followed by the
+        /// elements of the second sequence.</returns>
         public static IEnumerable<int> operator +(IEnumerable<int> left, IEnumerable<int> right)
             => left.Concat(right);
     }
@@ -44,29 +74,82 @@ public int Median
 public static class NumericStaticExtensions
 {
     // <StaticExtensions>
+    /// <summary>
+    /// Provides static extensions for the <see cref="IEnumerable{Int32}"/> type.
+    /// </summary>
     extension(IEnumerable<int>)
     {
         // Method:
+        /// <summary>
+        /// Generates a sequence of integers, starting from a specified value and incrementing by a given amount.
+        /// </summary>
+        /// <param name="low">The starting value of the sequence.</param>
+        /// <param name="count">The number of integers to generate. Must be non-negative.</param>
+        /// <param name="increment">The value by which to increment each subsequent integer in the sequence.</param>
+        /// <returns>
+        /// An enumerable collection of integers, beginning with the specified starting value and containing the
+        /// specified number of elements, each incremented by the given amount.
+        /// </returns>
         public static IEnumerable<int> Generate(int low, int count, int increment)
         {
             for (int i = 0; i < count; i++)
                 yield return low + (i * increment);
         }
 
         // Property:
+        /// <summary>
+        /// Gets an empty sequence of integers representing the identity element for sequence operations.
+        /// </summary>
+        /// <remarks>
+        /// This property can be used as a neutral starting point when aggregating or composing
+        /// sequences of integers. The returned sequence is always empty and does not allocate any storage.
+        /// </remarks>
         public static IEnumerable<int> Identity => Enumerable.Empty<int>();
     }
     // </StaticExtensions>
 }
 
 // <GenericExtension>
+/// <summary>
+/// Contains generic extension members for sequences.
+/// </summary>
 public static class GenericExtensions
 {
+    /// <summary>
+    /// Defines extensions for generic sequences.
+    /// </summary>
+    /// <typeparam name="TReceiver">The type of elements in the receiver sequence.</typeparam>
+    /// <param name="source">The sequence used as a receiver.</param>
     extension<TReceiver>(IEnumerable<TReceiver> source)
     {
+        /// <summary>
+        /// Returns a sequence containing a specified number of elements from the source, starting at a given index.
+        /// </summary>
+        /// <param name="start">The zero-based index at which to begin retrieving elements. Must be greater than or equal to 0.</param>
+        /// <param name="count">The number of elements to return. Must be greater than or equal to 0.</param>
+        /// <returns>
+        /// An <see cref="IEnumerable{TReceiver}"/> that contains up to <paramref name="count"/> elements from the
+        /// source sequence, starting at the element at position <paramref name="start"/>. If <paramref name="start"/>
+        /// is greater than the number of elements in the source, an empty sequence is returned.
+        /// </returns>
         public IEnumerable<TReceiver> Spread(int start, int count)
             => source.Skip(start).Take(count);
 
+        /// <summary>
+        /// Returns a sequence that contains the elements of the original sequence followed by the elements of a
+        /// specified sequence, each transformed by a converter function.
+        /// </summary>
+        /// <remarks>
+        /// Enumeration of the returned sequence will not start until the sequence is iterated.
+        /// The converter function is applied to each element of the appended sequence as it is enumerated.
+        /// </remarks>
+        /// <typeparam name="TArg">The type of the elements in the sequence to append.</typeparam>
+        /// <param name="second">The sequence whose elements are to be appended after being converted. Cannot be null.</param>
+        /// <param name="Converter">A function to convert each element of the appended sequence to the result type. Cannot be null.</param>
+        /// <returns>
+        /// An IEnumerable<TReceiver> that contains the elements of the original sequence followed by the converted
+        /// elements of the specified sequence.
+        /// </returns>
         public IEnumerable<TReceiver> Append<TArg>(IEnumerable<TArg> second, Func<TArg, TReceiver> Converter)
         {
             foreach(TReceiver item in source)
@@ -79,11 +162,27 @@ public IEnumerable<TReceiver> Append<TArg>(IEnumerable<TArg> second, Func<TArg,
             }
         }
 
-        public IEnumerable<TReceiver> Prepend<TArg>(IEnumerable<TArg> second, Func<TArg, TReceiver> Converter)
+        /// <summary>
+        /// Returns a sequence that consists of the elements of the specified collection, transformed by the provided
+        /// converter, followed by the elements of the current sequence.
+        /// </summary>
+        /// <remarks>
+        /// Enumeration of the returned sequence will not start until the sequence is iterated.
+        /// Both the input collection and the converter function must not be null; otherwise, an exception will be
+        /// thrown at enumeration time.
+        /// </remarks>
+        /// <typeparam name="TArg">The type of the elements in the collection to prepend.</typeparam>
+        /// <param name="second">The collection whose elements are to be transformed and prepended to the current sequence. Cannot be null.</param>
+        /// <param name="converter">A function to convert each element of the prepended collection to the target type. Cannot be null.</param>
+        /// <returns>
+        /// An IEnumerable<TReceiver> that contains the converted elements of the specified collection followed by the
+        /// elements of the current sequence.
+        /// </returns>
+        public IEnumerable<TReceiver> Prepend<TArg>(IEnumerable<TArg> second, Func<TArg, TReceiver> converter)
         {
             foreach (TArg item in second)
             {
-                yield return Converter(item);
+                yield return converter(item);
             }
             foreach (TReceiver item in source)
             {

docs/csharp/language-reference/xmldoc/examples.md

@@ -1,30 +1,30 @@
 ---
 title: "Example XML documentation comments"
 description: See documentation examples on many different C# language elements. Learn which tags to use in different situations and for different language elements.
-ms.date: 07/14/2021
+ms.date: 12/11/2025
 ms.topic: how-to
 ---
 # Example XML documentation comments
 
-This article contains three examples for adding XML documentation comments to most C# language elements. The first example shows how you document a class with different members. The second shows how you would reuse explanations for a hierarchy of classes or interfaces. The third shows tags to use for generic classes and members. The second and third examples use concepts that are covered in the first example.
+This article contains three examples for adding XML documentation comments to most C# language elements. The first example shows how you document a class with different members. The second example shows how you can reuse explanations for a hierarchy of classes or interfaces. The third example shows tags to use for generic classes and members. The second and third examples use concepts that are covered in the first example.
 
 ## Document a class, struct, or interface
 
 The following example shows common language elements, and the tags you'll likely use to describe these elements.  The documentation comments describe the use of the tags, rather than the class itself.
 
 :::code language="csharp" source="./snippets/xmldoc/DocComments.cs" ID="ClassExample":::
 
-Adding documentation can clutter your source code with large sets of comments intended for users of your library. You use the `<Include>` tag to separate your XML comments from your source. Your source code references an XML file with the `<Include>` tag:
+Adding documentation can clutter your source code with large sets of comments intended for users of your library. Use the `<Include>` tag to separate your XML comments from your source. Your source code references an XML file by using the `<Include>` tag:
 
 :::code language="csharp" source="./snippets/xmldoc/DocComments.cs" ID="IncludeTag":::
 
 The second file, *xml_include_tag.xml*, contains the documentation comments.
 
-:::code language="xml" source="./snippets/xmldoc/xml_include_tag.xml" :::
+:::code language="xml" source="./snippets/xmldoc/xml_include_tag.xml":::
 
 ## Document a hierarchy of classes and interfaces
 
-The `<inheritdoc>` element means a type or member *inherits* documentation comments from a base class or interface. You can also use the `<inheritdoc>` element with the `cref` attribute to inherit comments from a member of the same type. The following example shows ways to use this tag. Note that when you add the `inheritdoc` attribute to a type, member comments are inherited. You can prevent the use of inherited comments by writing comments on the members in the derived type. Those will be chosen over the inherited comments.
+The `<inheritdoc>` element means a type or member *inherits* documentation comments from a base class or interface. You can also use the `<inheritdoc>` element with the `cref` attribute to inherit comments from a member of the same type. The following example shows ways to use this tag. When you add the `inheritdoc` attribute to a type, member comments are inherited. You can prevent the use of inherited comments by writing comments on the members in the derived type. Those comments are chosen over the inherited comments.
 
 :::code language="csharp" source="./snippets/xmldoc/DocComments.cs" ID="InheritDocTag":::
 
@@ -34,13 +34,21 @@ Use the `<typeparam>` tag to describe type parameters on generic types and metho
 
 :::code language="csharp" source="./snippets/xmldoc/DocComments.cs" ID="GenericExample":::
 
+## Extension members
+
+Add XML comments for `<summary>`, `<param>`, and, if necessary, `<typeparam>` to describe the receiver parameter on extension members:
+
+:::code language="csharp" source="./snippets/xmldoc/DocComments.cs" ID="ExtensionExample":::
+
+The C# compiler copies the XML nodes from the `extension` block to all members declared in that block.
+
 ## Math class example
 
 The following code shows a realistic example of adding doc comments to a math library.
 
 :::code language="csharp" source="./snippets/xmldoc/tagged-library.cs":::
 
-You may find that the code is obscured by all the comments. The final example shows how you would adapt this library to use the `include` tag. You move all the documentation to an XML file:
+You might find that the code is obscured by all the comments. The final example shows how you adapt this library to use the `include` tag. You move all the documentation to an XML file:
 
 :::code language="xml" source="./snippets/xmldoc/include.xml":::
 
@@ -52,4 +60,4 @@ The code uses the `<include>` tag to reference the appropriate element in the XM
 - The `file` attribute represents the name of the XML file containing the documentation.
 - The `path` attribute represents an [XPath](../../../standard/data/xml/xpath-queries-and-namespaces.md) query to the `tag name` present in the specified `file`.
 - The `name` attribute represents the name specifier in the tag that precedes the comments.
-- The `id` attribute, which can be used in place of `name`, represents the ID for the tag that precedes the comments.
+- The `id` attribute, which you can use in place of `name`, represents the ID for the tag that precedes the comments.