diff --git a/docs/csharp/fundamentals/tutorials/snippets/xml-documentation/BankAccount.cs b/docs/csharp/fundamentals/tutorials/snippets/xml-documentation/BankAccount.cs index c41fa0e1ff61a..111fd44c36983 100644 --- a/docs/csharp/fundamentals/tutorials/snippets/xml-documentation/BankAccount.cs +++ b/docs/csharp/fundamentals/tutorials/snippets/xml-documentation/BankAccount.cs @@ -163,8 +163,6 @@ public string GetAccountHistory() return report.ToString(); } - // Added for OO tutorial: - /// /// 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. diff --git a/docs/csharp/fundamentals/tutorials/snippets/xml-documentation/GiftCardAccount.cs b/docs/csharp/fundamentals/tutorials/snippets/xml-documentation/GiftCardAccount.cs index 9ec4f25976d95..c7d4d2e1c469d 100644 --- a/docs/csharp/fundamentals/tutorials/snippets/xml-documentation/GiftCardAccount.cs +++ b/docs/csharp/fundamentals/tutorials/snippets/xml-documentation/GiftCardAccount.cs @@ -1,9 +1,6 @@ namespace OOProgramming; -/// -/// Represents a gift card account that extends with optional recurring monthly deposits. -/// Designed for prepaid gift cards that can optionally receive automatic monthly top-ups. -/// +/// /// /// 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 diff --git a/docs/csharp/fundamentals/tutorials/snippets/xml-documentation/InterestEarningAccount.cs b/docs/csharp/fundamentals/tutorials/snippets/xml-documentation/InterestEarningAccount.cs index 15a9f77c52e29..abeb171e68792 100644 --- a/docs/csharp/fundamentals/tutorials/snippets/xml-documentation/InterestEarningAccount.cs +++ b/docs/csharp/fundamentals/tutorials/snippets/xml-documentation/InterestEarningAccount.cs @@ -1,9 +1,7 @@ namespace OOProgramming; -/// -/// Represents an interest-earning bank account that extends with monthly interest payments. -/// Earns interest on balances above $500 at a rate of 2% annually, applied monthly. -/// +// +/// /// /// 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. @@ -11,6 +9,7 @@ /// This account type uses the standard minimum balance of $0 from the base class. /// public class InterestEarningAccount : BankAccount +// { /// /// Initializes a new instance of the class with the specified owner name and initial balance. diff --git a/docs/csharp/fundamentals/tutorials/snippets/xml-documentation/LineOfCreditAccount.cs b/docs/csharp/fundamentals/tutorials/snippets/xml-documentation/LineOfCreditAccount.cs index 3e6dac527be6e..fc4031a8a3c91 100644 --- a/docs/csharp/fundamentals/tutorials/snippets/xml-documentation/LineOfCreditAccount.cs +++ b/docs/csharp/fundamentals/tutorials/snippets/xml-documentation/LineOfCreditAccount.cs @@ -1,9 +1,6 @@ namespace OOProgramming; -/// -/// Represents a line of credit account that extends with credit limit functionality. -/// Allows negative balances up to a specified credit limit and applies monthly interest charges on outstanding balances. -/// +/// /// /// 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 diff --git a/docs/csharp/fundamentals/tutorials/xml-documentation.md b/docs/csharp/fundamentals/tutorials/xml-documentation.md index fed376ec885c0..5c0a77ead845b 100644 --- a/docs/csharp/fundamentals/tutorials/xml-documentation.md +++ b/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 ``` -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 `` 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 `` 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 `` element inside the derived member's documentation block. You can still append more elements (such as extra `` details) after `` 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 `` element inside the derived member's documentation block. You can still append more elements (such as extra `` details) after `` to document the specialized behavior: -```csharp -/// -/// Adds monthly interest during month-end processing. -public class SavingsAccount : BankAccount { /* ... */ } -``` +:::code language="csharp" source="./snippets/xml-documentation/InterestEarningAccount.cs" id="InterestEarningAccountComments"::: > [!NOTE] > `` 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: