Skip to content

Commit b7cc71c

Browse files
CopilotBillWagner
andauthored
Add note about unparsed markup in XML documentation comments without tags (#48918)
* Initial plan * Add note about broken XML tags in comments without proper XML formatting Co-authored-by: BillWagner <[email protected]> --------- Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: BillWagner <[email protected]>
1 parent 02e5e10 commit b7cc71c

File tree

1 file changed

+3
-0
lines changed

1 file changed

+3
-0
lines changed

docs/fsharp/language-reference/xml-documentation.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,9 @@ that immediately follows. Use this method when you want to write only a brief su
3939
The comment is encoded to XML during documentation preparation, so characters such as `<`, `>`, and `&` need not be escaped. If you don't specify a summary tag
4040
explicitly, you should not specify other tags, such as **param** or **returns** tags.
4141

42+
> [!NOTE]
43+
> When you use comments without XML tags, any markup you include (such as HTML tags or XML-like syntax) will not be parsed or checked by the compiler or F# tooling. Some external tools like GitHub might attempt to parse the markup, but they can fail if the syntax contains errors. If you need to use XML tags in your documentation, wrap your comments with proper XML tags like `<summary>` to ensure they're validated by the compiler when `--warnon:3390` is enabled.
44+
4245
The following example shows the alternative method, without XML tags. In this example, the entire text in the comment is considered a summary.
4346

4447
[!code-fsharp[Main](~/samples/snippets/fsharp/lang-ref-2/snippet7102.fs)]

0 commit comments

Comments
 (0)