see and seealso elements support more than cref but it is not documented

[meziantou]

The documentation for <see> and <seealso> only mention the cref attribute. However, it is possible to use <seealso href="https://..." />, <seealso href="https://...">text</seealso> or <see langword="false" />

Also, there is no mention for a few formatting elements such as <i> / <em>, <b> / <strong>, <u>, <br>, <a> that seems to be supported.

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 39152ded-70ce-012d-ffc3-a8b1a78f3308
• Version Independent ID: 809078f6-169a-0ffe-5f33-d5a359aeefc5
• Content: Documenting your code with XML comments
• Content Source: docs/csharp/codedoc.md
• Product: dotnet-csharp
• Technology: csharp-fundamentals
• GitHub Login: @BillWagner
• Microsoft Alias: wiwagn

[BillWagner]

Thanks for posting this @meziantou We've been collecting a number of concerns regarding our articles on C# XML doc comments.

We're still discussing how best to resolve these. From the perspective of the C# compiler, any valid XML is allowed. However, whether or not a tag is useful depends on the tooling used to convert the compiler's XML output into reasonable human docs.

I've added this to our backlog, and the project where we'll address these.

[meziantou]

Note that the tags / attributes I've listed in the issue are the ones that Roslyn understands and formats correctly (at least in VS). The following file contains all the supported tags/attributes:

https://github.com/dotnet/roslyn/blob/1223006dad529b84b0a9d81c4dcee239fe87b772/src/Features/Core/Portable/DocumentationComments/AbstractDocumentationCommentFormattingService.cs#L305