From cad1bcc9880612fff412c016779533651b7e959f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 1 Jul 2025 17:58:33 +0000 Subject: [PATCH 1/3] Initial plan From 748974812ae0f6a62fcd051612664dc700cbb9c3 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 1 Jul 2025 18:06:38 +0000 Subject: [PATCH 2/3] Enhance XML documentation for href attribute and br tag usage Co-authored-by: BillWagner <493969+BillWagner@users.noreply.github.com> --- .../xmldoc/recommended-tags.md | 15 ++++- .../snippets/xmldoc/HrefAndBrExamples.cs | 60 +++++++++++++++++++ 2 files changed, 73 insertions(+), 2 deletions(-) create mode 100644 docs/csharp/language-reference/xmldoc/snippets/xmldoc/HrefAndBrExamples.cs diff --git a/docs/csharp/language-reference/xmldoc/recommended-tags.md b/docs/csharp/language-reference/xmldoc/recommended-tags.md index 8f3b24554d736..cffc54223ab37 100644 --- a/docs/csharp/language-reference/xmldoc/recommended-tags.md +++ b/docs/csharp/language-reference/xmldoc/recommended-tags.md @@ -118,6 +118,9 @@ Some of the recommended tags can be used on any language element. Others have mo The compiler verifies the syntax of the elements followed by a single \* in the following list. Visual Studio provides IntelliSense for the tags verified by the compiler and all tags followed by \*\* in the following list. In addition to the tags listed here, the compiler and Visual Studio validate the ``, ``, ``, `
`, and `` tags. The compiler also validates ``, which is deprecated HTML. +> [!NOTE] +> HTML tags like `
` are useful for formatting within documentation comments. The `
` tag creates line breaks, while other HTML tags provide text formatting. These tags work in IntelliSense tooltips and generated documentation. + - [General Tags](#general-tags) used for multiple elements - These tags are the minimum set for any API. - [``](#summary): The value of this element is displayed in IntelliSense in Visual Studio. - [``](#remarks) \*\* @@ -241,6 +244,10 @@ The `` tag lets you describe the value that a property represents. When y The `` tag is for use inside a tag, such as [\](#summary), [\](#remarks), or [\](#returns), and lets you add structure to the text. The `` tag creates a double spaced paragraph. Use the `
` tag if you want a single spaced paragraph. +Here's an example showing the difference between `` and `
`: + +:::code language="csharp" source="./snippets/xmldoc/HrefAndBrExamples.cs" id="FormattingExample"::: + ### \ ```xml @@ -368,11 +375,15 @@ The XML output for this method is shown in the following example: ``` - `cref="member"`: A reference to a member or field that is available to be called from the current compilation environment. The compiler checks that the given code element exists and passes `member` to the element name in the output XML. Place *member* within quotation marks ("). You can provide different link text for a "cref", by using a separate closing tag. -- `href="link"`: A clickable link to a given URL. For example, `GitHub` produces a clickable link with text :::no-loc text="GitHub"::: that links to `https://github.com`. +- `href="link"`: A clickable link to a given URL. For example, `GitHub` produces a clickable link with text :::no-loc text="GitHub"::: that links to `https://github.com`. Use `href` instead of `cref` when linking to external web pages, as `cref` is designed for code references and won't create clickable links for URLs. - `langword="keyword"`: A language keyword, such as `true` or one of the other valid [keywords](../keywords/index.md). The `` tag lets you specify a link from within text. Use [\](#seealso) to indicate that text should be placed in a See Also section. Use the [cref attribute](#cref-attribute) to create internal hyperlinks to documentation pages for code elements. You include the type parameters to specify a reference to a generic type or method, such as `cref="IDictionary{T, U}"`. Also, ``href`` is a valid attribute that functions as a hyperlink. +Here's an example showing the difference between `cref` and `href` when referencing external URLs: + +:::code language="csharp" source="./snippets/xmldoc/HrefAndBrExamples.cs" id="UrlLinkingExample"::: + ### \ ```xml @@ -392,7 +403,7 @@ The `cref` attribute in an XML documentation tag means "code reference." It spec ### href attribute -The `href` attribute means a reference to a web page. You can use it to directly reference online documentation about your API or library. +The `href` attribute means a reference to a web page. You can use it to directly reference online documentation about your API or library. When you need to link to external URLs in your documentation comments, use `href` instead of `cref` to ensure the links are clickable in IntelliSense tooltips and generated documentation. ## Generic types and methods diff --git a/docs/csharp/language-reference/xmldoc/snippets/xmldoc/HrefAndBrExamples.cs b/docs/csharp/language-reference/xmldoc/snippets/xmldoc/HrefAndBrExamples.cs new file mode 100644 index 0000000000000..3b363080c4bb1 --- /dev/null +++ b/docs/csharp/language-reference/xmldoc/snippets/xmldoc/HrefAndBrExamples.cs @@ -0,0 +1,60 @@ +using System; + +namespace XmlDocumentationExamples +{ + /// + /// This class demonstrates the use of href attribute and br tag in XML documentation. + /// + public class HrefAndBrExamples + { + // + /// + /// This method demonstrates URL linking: + /// (won't create clickable link) + /// C# documentation (creates clickable link) + /// + public void UrlLinkingExample() + { + // This method demonstrates the difference between cref and href for URLs + } + // + + // + /// + /// Example using para tags: + /// This is the first paragraph. + /// This is the second paragraph with double spacing. + /// + /// Example using br tags: + /// First line of text
+ /// Second line of text with single spacing
+ /// Third line of text + /// + public void FormattingExample() + { + // This method demonstrates paragraph and line break formatting + } + // + + /// + /// Comprehensive example showing different link types: + /// Console.WriteLine (code reference with custom text)
+ /// GitHub repository (external link)
+ /// (language keyword)
+ /// (type reference) + /// + /// + /// This example shows: + /// + /// Using cref for code elements + /// Using href for external URLs + /// Using langword for language keywords + /// Using br for line breaks in summaries + /// + /// + public void ComprehensiveExample() + { + // This method demonstrates various linking and formatting options + } + } +} \ No newline at end of file From 59b0bc012f1e3e8fae830537a824734f76108ca3 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 2 Jul 2025 13:43:06 +0000 Subject: [PATCH 3/3] Update URLs to use learn.microsoft.com domain Co-authored-by: BillWagner <493969+BillWagner@users.noreply.github.com> --- docs/csharp/language-reference/xmldoc/recommended-tags.md | 2 +- .../xmldoc/snippets/xmldoc/HrefAndBrExamples.cs | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/csharp/language-reference/xmldoc/recommended-tags.md b/docs/csharp/language-reference/xmldoc/recommended-tags.md index cffc54223ab37..40e376c08ed90 100644 --- a/docs/csharp/language-reference/xmldoc/recommended-tags.md +++ b/docs/csharp/language-reference/xmldoc/recommended-tags.md @@ -375,7 +375,7 @@ The XML output for this method is shown in the following example: ``` - `cref="member"`: A reference to a member or field that is available to be called from the current compilation environment. The compiler checks that the given code element exists and passes `member` to the element name in the output XML. Place *member* within quotation marks ("). You can provide different link text for a "cref", by using a separate closing tag. -- `href="link"`: A clickable link to a given URL. For example, `GitHub` produces a clickable link with text :::no-loc text="GitHub"::: that links to `https://github.com`. Use `href` instead of `cref` when linking to external web pages, as `cref` is designed for code references and won't create clickable links for URLs. +- `href="link"`: A clickable link to a given URL. For example, `GitHub` produces a clickable link with text :::no-loc text="GitHub"::: that links to `https://github.com`. Use `href` instead of `cref` when linking to external web pages, as `cref` is designed for code references and won't create clickable links for external URLs. - `langword="keyword"`: A language keyword, such as `true` or one of the other valid [keywords](../keywords/index.md). The `` tag lets you specify a link from within text. Use [\](#seealso) to indicate that text should be placed in a See Also section. Use the [cref attribute](#cref-attribute) to create internal hyperlinks to documentation pages for code elements. You include the type parameters to specify a reference to a generic type or method, such as `cref="IDictionary{T, U}"`. Also, ``href`` is a valid attribute that functions as a hyperlink. diff --git a/docs/csharp/language-reference/xmldoc/snippets/xmldoc/HrefAndBrExamples.cs b/docs/csharp/language-reference/xmldoc/snippets/xmldoc/HrefAndBrExamples.cs index 3b363080c4bb1..3ba7b4df6cf1a 100644 --- a/docs/csharp/language-reference/xmldoc/snippets/xmldoc/HrefAndBrExamples.cs +++ b/docs/csharp/language-reference/xmldoc/snippets/xmldoc/HrefAndBrExamples.cs @@ -10,8 +10,8 @@ public class HrefAndBrExamples // /// /// This method demonstrates URL linking: - /// (won't create clickable link) - /// C# documentation (creates clickable link) + /// (won't create clickable link) + /// C# documentation (creates clickable link) /// public void UrlLinkingExample() {