This PR enhances the XML documentation to better explain the href attribute and <br/> tag usage in C# documentation comments, addressing confusion about when and how to use these features.

Changes Made

Enhanced href attribute documentation

• Added clear explanation that href creates clickable links while cref with URLs does not
• Added practical example showing the difference between cref and href for external URLs
• Enhanced the href attribute section with guidance on when to use it vs cref

Improved <br/> tag documentation

• Added comprehensive example showing the difference between <para> (double-spaced) and <br/> (single-spaced) formatting
• Clarified when to use each tag for different spacing needs

Added working code examples

• Created HrefAndBrExamples.cs with practical examples that demonstrate the concepts
• Examples show the compiler warning (CS1584) when using cref with URLs, reinforcing why href should be used instead
• Code examples are properly tagged for snippet inclusion in documentation

Updated introduction section

• Added note explaining that HTML tags like <br/> work in IntelliSense tooltips and generated documentation
• Made HTML tag support more prominent in the overview

Example of the key difference addressed:

/// <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 ExampleMethod() { }

The documentation now clearly addresses the original concern that these features were available in IntelliSense but not properly documented.

Fixes #18859.

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Internal previews