XML Documentation (F#)
You can produce documentation from triple-slash (///) code comments in F#. XML comments can precede declarations in code files (.fs) or signature (.fsi) files.
Generating Documentation from Comments
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 enables you to produce an XML file that contains information that you can convert into documentation by using a tool such as Sandcastle. 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.
For more information about how to generate documentation from XML, see XML Documentation Comments (C# Programming Guide).
Recommended Tags
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.
Tag syntax |
Description |
|---|---|
<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. |
<summary> text </summary> |
Specifies that text is a brief description of the program element. The description is usually one or two sentences. |
<remarks> text </remarks> |
Specifies that text contains supplementary information about the program element. |
<param name="name"> description </param> |
Specifies the name and description for a function or method parameter. |
<typeparam name="name"> description </typeparam> |
Specifies the name and description for a type parameter. |
<returns> text </returns> |
Specifies that text describes the return value of a function or method. |
<exception cref="type"> description </exception> |
Specifies the type of exception that can be generated and the circumstances under which it is thrown. |
<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. |
<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. |
<para> text </para> |
Specifies a paragraph of text. This is used to separate text inside the remarks tag. |
Example
Description
The following is a typical XML documentation comment in a signature file.
Code
/// <summary>Builds a new string whose characters are the results of applying the function <c>mapping</c>
/// to each of the characters of the input string and concatenating the resulting
/// strings.</summary>
/// <param name="mapping">The function to produce a string from each character of the input string.</param>
///<param name="str">The input string.</param>
///<returns>The concatenated string.</returns>
///<exception cref="System.ArgumentNullException">Thrown when the input string is null.</exception>
val collect : (char -> string) -> string -> string
Example
Description
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.
Code
/// Creates a new string whose characters are the result of applying
/// the function mapping to each of the characters of the input string
/// and concatenating the resulting strings.
val collect : (char -> string) -> string -> string