Enhance XML documentation for href attribute and br tag usage

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

Author: Copilot

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 `<b>`, `<i>`, `<u>`, `<br/>`, and `<a>` tags. The compiler also validates `<tt>`, which is deprecated HTML.
 
+> [!NOTE]
+> HTML tags like `<br/>` are useful for formatting within documentation comments. The `<br/>` 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>`](#summary): The value of this element is displayed in IntelliSense in Visual Studio.
   - [`<remarks>`](#remarks) \*\*
@@ -241,6 +244,10 @@ The `<value>` tag lets you describe the value that a property represents. When y
 
 The `<para>` tag is for use inside a tag, such as [\<summary>](#summary), [\<remarks>](#remarks), or [\<returns>](#returns), and lets you add structure to the text. The `<para>` tag creates a double spaced paragraph. Use the `<br/>` tag if you want a single spaced paragraph.
 
+Here's an example showing the difference between `<para>` and `<br/>`:
+
+:::code language="csharp" source="./snippets/xmldoc/HrefAndBrExamples.cs" id="FormattingExample":::
+
 ### \<list>
 
 ```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, `<see href="https://github.com">GitHub</see>` 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, `<see href="https://github.com">GitHub</see>` 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 `<see>` tag lets you specify a link from within text. Use [\<seealso>](#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":::
+
 ### \<seealso>
 
 ```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
 

docs/csharp/language-reference/xmldoc/snippets/xmldoc/HrefAndBrExamples.cs

@@ -0,0 +1,60 @@
+using System;
+
+namespace XmlDocumentationExamples
+{
+    /// <summary>
+    /// This class demonstrates the use of href attribute and br tag in XML documentation.
+    /// </summary>
+    public class HrefAndBrExamples
+    {
+        //<UrlLinkingExample>
+        /// <summary>
+        /// This method demonstrates URL linking:
+        /// <see cref="https://docs.microsoft.com/dotnet/csharp"/> (won't create clickable link)
+        /// <see href="https://docs.microsoft.com/dotnet/csharp">C# documentation</see> (creates clickable link)
+        /// </summary>
+        public void UrlLinkingExample()
+        {
+            // This method demonstrates the difference between cref and href for URLs
+        }
+        //</UrlLinkingExample>
+
+        //<FormattingExample>
+        /// <summary>
+        /// Example using para tags:
+        /// <para>This is the first paragraph.</para>
+        /// <para>This is the second paragraph with double spacing.</para>
+        /// 
+        /// Example using br tags:
+        /// First line of text<br/>
+        /// Second line of text with single spacing<br/>
+        /// Third line of text
+        /// </summary>
+        public void FormattingExample()
+        {
+            // This method demonstrates paragraph and line break formatting
+        }
+        //</FormattingExample>
+
+        /// <summary>
+        /// Comprehensive example showing different link types:
+        /// <see cref="Console.WriteLine(string)">Console.WriteLine</see> (code reference with custom text)<br/>
+        /// <see href="https://github.com/dotnet/docs">GitHub repository</see> (external link)<br/>
+        /// <see langword="null"/> (language keyword)<br/>
+        /// <see cref="string"/> (type reference)
+        /// </summary>
+        /// <remarks>
+        /// This example shows:
+        /// <list type="bullet">
+        /// <item>Using cref for code elements</item>
+        /// <item>Using href for external URLs</item>
+        /// <item>Using langword for language keywords</item>
+        /// <item>Using br for line breaks in summaries</item>
+        /// </list>
+        /// </remarks>
+        public void ComprehensiveExample()
+        {
+            // This method demonstrates various linking and formatting options
+        }
+    }
+}