diff --git a/docs/csharp/language-reference/xmldoc/recommended-tags.md b/docs/csharp/language-reference/xmldoc/recommended-tags.md index 8f3b24554d736..40e376c08ed90 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 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. +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..3ba7b4df6cf1a --- /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