Skip to content

Commit 1acf542

Browse files
dsymecartermpYoussef1313
authored
Update xml-documentation.md (#20645)
* Update xml-documentation.md * Update xml-documentation.md * Update xml-documentation.md * Update docs/fsharp/language-reference/xml-documentation.md Co-authored-by: Phillip Carter <[email protected]> * Update docs/fsharp/language-reference/xml-documentation.md Co-authored-by: Phillip Carter <[email protected]> * Update docs/fsharp/language-reference/xml-documentation.md Co-authored-by: Phillip Carter <[email protected]> * Update docs/fsharp/language-reference/xml-documentation.md Co-authored-by: Phillip Carter <[email protected]> * Update docs/fsharp/language-reference/xml-documentation.md Co-authored-by: Phillip Carter <[email protected]> * Update docs/fsharp/language-reference/xml-documentation.md Co-authored-by: Phillip Carter <[email protected]> * Update docs/fsharp/language-reference/xml-documentation.md Co-authored-by: Youssef Victor <[email protected]> * Update docs/fsharp/language-reference/xml-documentation.md Co-authored-by: Youssef Victor <[email protected]> * Update docs/fsharp/language-reference/xml-documentation.md Co-authored-by: Youssef Victor <[email protected]> * Update xml-documentation.md * Update xml-documentation.md * Update xml-documentation.md Co-authored-by: Phillip Carter <[email protected]> Co-authored-by: Youssef Victor <[email protected]>
1 parent ed77902 commit 1acf542

File tree

1 file changed

+113
-28
lines changed

1 file changed

+113
-28
lines changed

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

Lines changed: 113 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,56 +1,141 @@
11
---
22
title: XML Documentation
33
description: Learn about support in F# for generating documentation from comments.
4-
ms.date: 05/16/2016
4+
ms.date: 09/15/2020
55
---
6-
# XML Documentation
6+
7+
# Document your code with XML comments
78

89
You can produce documentation from triple-slash (///) code comments in F#. XML comments can precede declarations in code files (.fs) or signature (.fsi) files.
910

10-
## Generating Documentation from Comments
11+
XML documentation comments are a special kind of comment, added above the definition of any user-defined type or member.
12+
They are special because they can be processed by the compiler to generate an XML documentation file at compile time.
13+
The compiler-generated XML file can be distributed alongside your .NET assembly so that IDEs can use tooltips to
14+
show quick information about types or members. Additionally, the XML file can be run through tools
15+
like [fsdocs](http://fsprojects.github.io/FSharp.Formatting/) to generate API reference websites.
1116

12-
The support in F# for generating documentation from comments is the same as that in other .NET Framework languages. As in other .NET Framework languages, the [-doc compiler option](./compiler-options.md) enables you to produce an XML file that contains information that you can convert into documentation by using a tool such as [DocFX](https://dotnet.github.io/docfx/) or [Sandcastle](https://github.com/EWSoftware/SHFB). The documentation generated by using tools that are designed for use with assemblies that are written in other .NET Framework languages generally produce a view of the APIs that is based on the compiled form of F# constructs. Unless tools specifically support F#, documentation generated by these tools does not match the F# view of an API.
17+
XML documentation comments, like all other comments, are ignored by the compiler, unless the options described below are enabled to check the validity and
18+
completeness of comments at compile-time.
1319

14-
For more information about how to generate documentation from XML, see [XML Documentation Comments &#40;C&#35; Programming Guide&#41;](../../csharp/programming-guide/xmldoc/index.md).
20+
You can generate the XML file at compile time by doing one of the following:
1521

16-
## Recommended Tags
22+
- You can add a `GenerateDocumentationFile` element to the `<PropertyGroup>` section of your `.fsproj` project file,
23+
which generates an XML file in the project directory with the same root filename as the assembly. For example:
24+
25+
```xml
26+
<GenerateDocumentationFile>true</GenerateDocumentationFile>
27+
```
28+
29+
- If you are developing an application using Visual Studio, right-click on the project and select **Properties**. In the properties dialog, select the **Build** tab, and check **XML documentation file**. You can also change the location to which the compiler writes the file.
1730

18-
There are two ways to write XML documentation comments. One is to just write the documentation directly in a triple-slash comment, without using XML tags. If you do this, 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. The other method is to use XML tags to provide more structured documentation. The second method enables you to specify separate notes for a short summary, additional remarks, documentation for each parameter and type parameter and exceptions thrown, and a description of the return value. The following table describes XML tags that are recognized in F# XML code comments.
31+
There are two ways to write XML documentation comments: with and without XML tags. Both use triple-slash comments.
1932

20-
|Tag syntax|Description|
21-
|----------|-----------|
22-
|**\<c\>**_text_**\</c\>**|Specifies that *text* is code. This tag can be used by documentation generators to display text in a font that is appropriate for code.|
23-
|**\<summary\>**_text_**\</summary\>**|Specifies that *text* is a brief description of the program element. The description is usually one or two sentences.|
24-
|**\<remarks\>**_text_**\</remarks\>**|Specifies that *text* contains supplementary information about the program element.|
25-
|**\<param name="**_name_**"\>**_description_**\</param\>**|Specifies the name and description for a function or method parameter.|
26-
|**\<typeparam name="**_name_**"\>**_description_**\</typeparam\>**|Specifies the name and description for a type parameter.|
27-
|**\<returns\>**_text_**\</returns\>**|Specifies that *text* describes the return value of a function or method.|
28-
|**\<exception cref="**_type_**"\>**_description_**\</exception\>**|Specifies the type of exception that can be generated and the circumstances under which it is thrown.|
29-
|**\<see cref="**_reference_**"\>**_text_**\</see\>**|Specifies an inline link to another program element. The *reference* is the name as it appears in the XML documentation file. The *text* is the text shown in the link.|
30-
|**\<seealso cref="**_reference_**"/\>**|Specifies a See Also link to the documentation for another type. The *reference* is the name as it appears in the XML documentation file. See Also links usually appear at the bottom of a documentation page.|
31-
|**\<para\>**_text_**\</para\>**|Specifies a paragraph of text. This is used to separate text inside the **remarks** tag.|
33+
## Comments without XML tags
3234

33-
## Example
35+
If a `///` comment does not start with a `<` then the entire comment text is taken as the summary documentation for the code construct
36+
that immediately follows. Use this method when you want to write only a brief summary for each construct.
37+
38+
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
39+
explicitly, you should not specify other tags, such as **param** or **returns** tags.
40+
41+
The following example shows the alternative method, without XML tags. In this example, the entire text in the comment is considered a summary.
42+
43+
[!code-fsharp[Main](~/samples/snippets/fsharp/lang-ref-2/snippet7102.fs)]
3444

35-
### Description
45+
## Comments with XML tags
3646

37-
The following is a typical XML documentation comment in a signature file.
47+
If a comment body begins with `<` (normally `<summary>`) then it is treated as an XML formatted comment
48+
body using XML tags. This second enables you to specify separate notes
49+
for a short summary, additional remarks, documentation for each parameter and type parameter and exceptions thrown, and a description of the return value.
3850

39-
### Code
51+
The following is a typical XML documentation comment in a signature file:
4052

4153
[!code-fsharp[Main](~/samples/snippets/fsharp/lang-ref-2/snippet7101.fs)]
4254

43-
## Example
55+
## Recommended Tags
4456

45-
### Description
57+
If you are using XML tags, the following table describes the outer tags recognized in F# XML code comments.
4658

47-
The following example shows the alternative method, without XML tags. In this example, the entire text in the comment is considered a summary. Note that if you do not specify a summary tag explicitly, you should not specify other tags, such as **param** or **returns** tags.
59+
| Tag syntax | Description |
60+
|---------------------------------------------|-----------|
61+
| `<summary>`**_text_**`</summary>` | Specifies that *text* is a brief description of the program element. The description is usually one or two sentences.|
62+
| `<remarks>`**_text_**`</remarks>` | Specifies that *text* contains supplementary information about the program element.|
63+
| `<param name="`**_name_**`">`**_description_**`</param>` | Specifies the name and description for a function or method parameter.|
64+
| `<typeparam name="`**_name_**`">`**_description_**`</typeparam>` | Specifies the name and description for a type parameter.|
65+
| `<returns>`**_text_**`</returns>` | Specifies that *text* describes the return value of a function or method.|
66+
| `<exception cref="`**_type_**`">`**_description_**`</exception>` |Specifies the type of exception that can be generated and the circumstances under which it is thrown.|
67+
| `<seealso cref="`**_reference_**`"/>` | Specifies a See Also link to the documentation for another type. The *reference* is the name as it appears in the XML documentation file. See Also links usually appear at the bottom of a documentation page.|
4868

49-
### Code
69+
The following table describes the tags for use inside description sections:
5070

51-
[!code-fsharp[Main](~/samples/snippets/fsharp/lang-ref-2/snippet7102.fs)]
71+
| Tag syntax | Description |
72+
|-------------------------------------------|-------------|
73+
| `<para>`**_text_**`</para>` | Specifies a paragraph of text. This is used to separate text inside the **remarks** tag.|
74+
| `<code>`**_text_**`</code>` | Specifies that *text* is multiple lines of code. This tag can be used by documentation generators to display text in a font that is appropriate for code.|
75+
| `<paramref name="`**_name_**`"/>` | Specifies a reference to a parameter in the same documentation comment.|
76+
| `<typeparamref name="`**_name_**`"/>` | Specifies a reference to a type parameter in the same documentation comment.|
77+
| `<c>`**_text_**`</c>` | Specifies that *text* is inline code. This tag can be used by documentation generators to display text in a font that is appropriate for code.|
78+
| `<see cref="`**_reference_**`">`**_text_**`</see>` | Specifies an inline link to another program element. The *reference* is the name as it appears in the XML documentation file. The *text* is the text shown in the link.|
79+
80+
### User-defined tags
81+
82+
The previous tags represent those that are recognized by the F# compiler and typical F# editor tooling. However, a user is free to define their own tags.
83+
Tools like fsdocs bring support for extra tags like [\<namespacedoc>](https://github.com/fsharp/fslang-design/blob/master/tooling/FST-1031-xmldoc-extensions.md).
84+
Custom or in-house documentation generation tools can also be used with the standard tags and multiple output formats from HTML to PDF can be supported.
85+
86+
## Compile-time checking
87+
88+
When `--warnon:3390` is enabled, the compiler verifies the syntax of the XML and the parameters referred to in `<param>` and `<paramref>` tags.
89+
90+
## Documenting F# Constructs
91+
92+
F# constructs such as modules, members, union cases and record fields are documented by a `///` comment immediately prior to their declaration.
93+
If needed, implicit constructors of classes are documented by giving a `///` comment prior to the argument list. For example:
94+
95+
```fsharp
96+
/// This is the type
97+
type SomeType
98+
/// This is the implicit constructor
99+
(a: int, b: int) =
100+
101+
/// This is the member
102+
member _.Sum() = a + b
103+
```
104+
105+
## Limitations
106+
107+
Some features of XML documentation in C# and other .NET languages are not supported in C#.
108+
109+
- In F#, cross-references must use the full XML signature of the corresponding symbol, for example `cref="T:System.Console"`.
110+
Simple C#-style cross-references such as `cref="Console"` are not elaborated to full XML signatures
111+
and these elements are not checked by the F# compiler. Some documentation tooling
112+
may allow the use of these these cross-references by subsequent processing, but the full signatures should be used.
113+
114+
- The tags `<include>`, `<inheritdoc>` are not supported by the F# compiler. No error is given if they are used, but
115+
they are simply copied to the generated documentation file without otherwise affecting the documentation generated.
116+
117+
- Cross-references are not checked by the F# compiler, even when `-warnon:3390` is used.
118+
119+
- The names used in the tags `<typeparam>` and `<typeparamref>` are not checked by the F# compiler, even when `--warnon:3390` is used.
120+
121+
- No warnings are given if documentation is missing, even when `--warnon:3390` is used.
122+
123+
## Recommendations
124+
125+
Documenting code is recommended for many reasons. What follows are some best practices, general use case scenarios, and things that you should know when using XML documentation tags in your F# code.
126+
127+
- Enable the option `--warnon:3390` in your code to help ensure your XML documentation is valid XML.
128+
129+
- Consider adding signature files to separate long XML documentation comments from your implementation.
130+
131+
- For the sake of consistency, all publicly visible types and their members should be documented. If you must do it, do it all.
132+
133+
- At a bare minimum, modules, types and their members should have a plain `///` comment or `<summary>` tag. This will show in an autocompletion tooltip window in F# editing tools.
134+
135+
- Documentation text should be written using complete sentences ending with full stops.
52136

53137
## See also
54138

139+
- [C# XML Documentation Comments &#40;C&#35; Programming Guide&#41;](../../csharp/programming-guide/xmldoc/index.md).
55140
- [F# Language Reference](index.md)
56141
- [Compiler Options](compiler-options.md)

0 commit comments

Comments
 (0)