Skip to content

Commit 7c70b11

Browse files
CopilotBillWagner
andcommitted
Add note about broken XML tags in comments without proper XML formatting
Co-authored-by: BillWagner <[email protected]>
1 parent e42ec37 commit 7c70b11

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)