Use snippets in article (#50263)

* Use snippets in article

Responding to #50244

These files should remain in the repo, and should generally be included in the article

* Apply suggestions from code review

Co-authored-by: Copilot <[email protected]>

---------

Co-authored-by: Copilot <[email protected]>

Author: BillWagner

docs/csharp/fundamentals/tutorials/snippets/xml-documentation/BankAccount.cs

@@ -163,8 +163,6 @@ public string GetAccountHistory()
         return report.ToString();
     }
 
-    // Added for OO tutorial:
-
     /// <summary>
     /// Performs month-end processing for the account. This virtual method can be overridden in derived classes
     /// to implement specific month-end behaviors such as interest calculations, fee assessments, or statement generation.

docs/csharp/fundamentals/tutorials/snippets/xml-documentation/GiftCardAccount.cs

@@ -1,9 +1,6 @@
 namespace OOProgramming;
 
-/// <summary>
-/// Represents a gift card account that extends <see cref="BankAccount"/> with optional recurring monthly deposits.
-/// Designed for prepaid gift cards that can optionally receive automatic monthly top-ups.
-/// </summary>
+/// <inheritdoc/>
 /// <remarks>
 /// A gift card account is a specialized prepaid account that can be loaded with an initial balance and optionally
 /// configured to receive automatic monthly deposits. This account type is ideal for gift cards, allowances, or

docs/csharp/fundamentals/tutorials/snippets/xml-documentation/InterestEarningAccount.cs

@@ -1,16 +1,15 @@
 namespace OOProgramming;
 
-/// <summary>
-/// Represents an interest-earning bank account that extends <see cref="BankAccount"/> with monthly interest payments.
-/// Earns interest on balances above $500 at a rate of 2% annually, applied monthly.
-/// </summary>
+// <InterestEarningAccountComments>
+/// <inheritdoc/>
 /// <remarks>
 /// An interest-earning account is a specialized savings account that rewards customers for maintaining higher balances.
 /// Interest is only earned when the account balance exceeds $500, encouraging customers to maintain substantial deposits.
 /// The annual interest rate of 2% is applied monthly to qualifying balances, providing a simple savings incentive.
 /// This account type uses the standard minimum balance of $0 from the base <see cref="BankAccount"/> class.
 /// </remarks>
 public class InterestEarningAccount : BankAccount
+// </InterestEarningAccountComments>
 {
     /// <summary>
     /// Initializes a new instance of the <see cref="InterestEarningAccount"/> class with the specified owner name and initial balance.

docs/csharp/fundamentals/tutorials/snippets/xml-documentation/LineOfCreditAccount.cs

@@ -1,9 +1,6 @@
 namespace OOProgramming;
 
-/// <summary>
-/// Represents a line of credit account that extends <see cref="BankAccount"/> with credit limit functionality.
-/// Allows negative balances up to a specified credit limit and applies monthly interest charges on outstanding balances.
-/// </summary>
+/// <inheritdoc/>
 /// <remarks>
 /// A line of credit account differs from a regular bank account in that it allows the balance to go negative
 /// up to a predefined credit limit. When the balance is negative (indicating borrowed money), the account

docs/csharp/fundamentals/tutorials/xml-documentation.md

@@ -1,7 +1,7 @@
 ---
 title: Generate XML documentation from your source code
 description: "Learn to add `///` comments that generate XML documentation directly from your source code. Learn which tags are available and how to add documentation blocks to types and members."
-ms.topic: tutorial  #Don't change.
+ms.topic: tutorial
 ms.date: 10/14/2025
 ai-usage: ai-assisted
 #customer intent: As a developer, I want to generate XML documentation comments so that other developers can use my code successfully.
@@ -50,7 +50,9 @@ Build the project now. You see warnings for any public members that are missing
 </doc>
 ```
 
-With the file in place, start adding targeted XML comments and immediately verify how each one appears in the generated output.
+With the file in place, start adding targeted XML comments and immediately verify how each one appears in the generated output. Start with the `Transaction` record type:
+
+:::code language="csharp" source="./snippets/xml-documentation/transaction.cs":::
 
 ## Add documentation comments
 
@@ -65,6 +67,10 @@ You now cycle through the build warnings to add concise, useful documentation to
 1. For methods that return a value, add `<returns>` with a short description of what callers receive. Avoid repeating the method name or managed type.
 1. Work with the `BankAccount` base class first.
 
+Your version should look something like the following code:
+
+:::code language="csharp" source="./snippets/xml-documentation/BankAccount.cs":::
+
 When you're done, open the regenerated XML file and confirm that each member appears with your new elements. A trimmed portion might look like this:
 
 ```xml
@@ -83,19 +89,17 @@ When you're done, open the regenerated XML file and confirm that each member app
 
 ## Use `<inheritdoc/>` in derived classes
 
-If you derive from `BankAccount` (for example, a `SavingsAccount` that applies interest), you can inherit base documentation instead of copying it. Add a self-closing `<inheritdoc/>` element inside the derived member's documentation block. You can still append more elements (such as extra `<remarks>` details) after `<inheritdoc/>` to document the specialized behavior.
+If you derive from `BankAccount` (for example, a `SavingsAccount` that applies interest), you can inherit base documentation instead of copying it. Add a self-closing `<inheritdoc/>` element inside the derived member's documentation block. You can still append more elements (such as extra `<remarks>` details) after `<inheritdoc/>` to document the specialized behavior:
 
-```csharp
-/// <inheritdoc/>
-/// <remarks>Adds monthly interest during month-end processing.</remarks>
-public class SavingsAccount : BankAccount { /* ... */ }
-```
+:::code language="csharp" source="./snippets/xml-documentation/InterestEarningAccount.cs" id="InterestEarningAccountComments":::
 
 > [!NOTE]
 > `<inheritdoc/>` reduces duplication and helps maintain consistency when you update base type documentation later.
 
 After you finish documenting the public surface, build one final time to confirm there are no remaining CS1591 warnings. Your project now produces useful IntelliSense and a structured XML file ready for publishing workflows.
 
+You can see the full annotated sample in [the source folder](https://github.com/dotnet/docs/tree/main/docs/csharp/fundamentals/tutorials/snippets/xml-documentation) of the [dotnet/docs](https://github.com/dotnet/docs) repository on GitHub.
+
 ## Build output from comments
 
 You can explore more by trying any of these tools to create output from XML comments: