Add note about unparsed markup in XML documentation comments without tags

[Copilot]

Fixes #34903

This PR addresses the issue where developers might not realize that markup (such as HTML tags or XML-like syntax) included in /// comments without proper XML tags will not be parsed or validated by the F# compiler or tooling.

Changes

Added a NOTE block to the "Comments without XML tags" section in docs/fsharp/language-reference/xml-documentation.md that clarifies:

• Markup in comments without XML tags is not parsed or checked by the compiler or F# tooling
• External tools like GitHub might attempt to parse the markup but can fail if there are syntax errors
• Users should wrap comments with proper XML tags like <summary> if they want validation when --warnon:3390 is enabled

Context

As noted in the original issue, developers can accidentally include broken XML/HTML markup in their /// comments assuming it will work or be validated, only to discover issues later when external tools attempt to parse it. The F# compiler only validates XML syntax when comments use proper XML tags and the --warnon:3390 flag is enabled.

This note helps developers understand the limitations and make informed decisions about their documentation format.

Verification

The change:

• Follows the Microsoft Writing Style Guide (conversational tone, second person, present tense)
• Uses the standard > [!NOTE] format consistent with other notes in F# documentation
• Is minimal and surgical - only adds the necessary clarification without modifying existing content
• Will be validated by the repository's markdownlint CI/CD pipeline

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Needs to explain problems with broken tags</issue_title>
<issue_description>Further to:

If a /// comment does not start with a <, then the entire comment text is taken as the summary documentation for the code construct that immediately follows. Use this method when you want to write only a brief summary for each construct.

I'd suggest adding a sentence such as:

Note that markup in summary comments not surrounded by tags will not be parsed or checked by the compiler or tools (although some tools like GitHub will attempt to parse it, but will fail if there are such syntax errors).

Arguably there should be a warning emitted by the compiler if there are xml tags within a comment that are not bracketed as such - right now I'm finding places where my assumption that it would Just Work broke by looking for /// [^<].*<

Even more arguably, there should be a feature request to the compiler to treat triple (or 4?!) slash sections as if they have an implicit <remarks> wrapping unless they have a different tag wrapping them?

As a side note, I only figured this out after N years of the tooling and/or my laziness and bad assumptions misleading me into thinking it would Just Work - see jet/FsCodec#67. The same codebase was also reviewed by a very knowledgeable C# developer (@CumpsD) who I assume also assumed my pidgin syntax was kosher.

While I'm putting even more context into the wrong place.... Should the doc here mention that there are implicit <br/>s added when using non-tagged comments that one'll need to manually insert when you convert it? (could/should tooling offer a conversion step?)

(Another different way of addressing the needs of terse markup for xmldoc might be be to map markdown-style usage of backtick wrapping to <c>code</c> - I assume there are issues in the roslyn and/or F# repos requesting similar)

---

Document Details

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

• ID: 1a8fbc01-942f-ac15-e06b-2e50c45e8183
• Version Independent ID: 788235a1-2b43-1607-b24b-57c0552fd890
• Content: XML Documentation - F#
• Content Source: docs/fsharp/language-reference/xml-documentation.md
• Product: dotnet-fsharp
• GitHub Login: @cartermp
• Microsoft Alias: dotnetcontent</issue_description>

Comments on the Issue (you are @copilot in this section)

@BillWagner The compiler won't emit a warning, but it's worth adding a note in this article.

Fixes #26333

---

💡 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

📄 File	🔗 Preview link
docs/fsharp/language-reference/xml-documentation.md	docs/fsharp/language-reference/xml-documentation