Needs to explain problems with broken tags

[bartelink]

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

---

Associated WorkItem - 496354

[BillWagner]

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