From 8f89401cf7ac87282a2f3a7ea394c58cad081603 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 15 Sep 2020 14:05:51 +0100 Subject: [PATCH 01/15] Update xml-documentation.md --- .../language-reference/xml-documentation.md | 125 +++++++++++++++--- 1 file changed, 108 insertions(+), 17 deletions(-) diff --git a/docs/fsharp/language-reference/xml-documentation.md b/docs/fsharp/language-reference/xml-documentation.md index c7bfd07f603e4..4a236008a95ee 100644 --- a/docs/fsharp/language-reference/xml-documentation.md +++ b/docs/fsharp/language-reference/xml-documentation.md @@ -3,54 +3,145 @@ title: XML Documentation description: Learn about support in F# for generating documentation from comments. ms.date: 05/16/2016 --- -# XML Documentation + +# Document your code with XML comments 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 +XML documentation comments are a special kind of comment, added above the definition of any user-defined type or member. +They are special because they can be processed by the compiler to generate an XML documentation file at compile time. +The compiler-generated XML file can be distributed alongside your .NET assembly so that IDEs can use tooltips to +show quick information about types or members. Additionally, the XML file can be run through tools +like [fsdocs](http://fsprojects.github.io/FSharp.Formatting/) to generate API reference websites. + +XML documentation comments, like all other comments, are ignored by the compiler, unless the options described below are enabled to check the validity and +completeness of comments at compile-time. + +You can generate the XML file at compile time by doing one of the following: + +- If you are developing an application with .NET Core from the command line, you can + add a `GenerateDocumentationFile` element to the `` section of your .fsproj project file. You can + also specify the path to the documentation file directly using [`DocumentationFile` element](/visualstudio/msbuild/common-msbuild-project-properties). The + following example generates an XML file in the project directory with the same root filename as the assembly: + + ```xml + true + ``` + + This is equivalent to the following: + + ```xml + bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml + ``` + +- 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. + +- If you are compiling a .NET application from the command line, add the [-doc compiler option](./compiler-options.md) when compiling. + +### Writing XML Documentation -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. +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. -For more information about how to generate documentation from XML, see [XML Documentation Comments (C# Programming Guide)](../../csharp/programming-guide/xmldoc/index.md). +## Comments without XML tags + +If a comment does not start with a `<` then the comment is interpreted as a `` section. 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 explicitly, you should +not specify other tags, such as **param** or **returns** tags. + +The following example shows the alternative method, without XML tags. In this example, the entire text in the comment is considered a summary. + +[!code-fsharp[Main](~/samples/snippets/fsharp/lang-ref-2/snippet7102.fs)] + +## Comments with XML tags + +If the comment body begins with `<` then it is treated as an XML formatted comment body using XML tags. The following is a typical XML documentation comment in a signature file: + +[!code-fsharp[Main](~/samples/snippets/fsharp/lang-ref-2/snippet7101.fs)] ## 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. +If using XML tags, the following table describes the outer tags recognized in F# XML code comments. |Tag syntax|Description| |----------|-----------| -|**\**_text_**\**|Specifies that *text* is code. This tag can be used by documentation generators to display text in a font that is appropriate for code.| |**\**_text_**\**|Specifies that *text* is a brief description of the program element. The description is usually one or two sentences.| |**\**_text_**\**|Specifies that *text* contains supplementary information about the program element.| |**\**_description_**\**|Specifies the name and description for a function or method parameter.| |**\**_description_**\**|Specifies the name and description for a type parameter.| |**\**_text_**\**|Specifies that *text* describes the return value of a function or method.| |**\**_description_**\**|Specifies the type of exception that can be generated and the circumstances under which it is thrown.| -|**\**_text_**\**|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.| |**\**|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.| + +The following table describes the tags for use inside description sections: + +|Tag syntax|Description| +|----------|-----------| |**\**_text_**\**|Specifies a paragraph of text. This is used to separate text inside the **remarks** tag.| +|**\**_text_**\**|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.| +|**\**|Specifies a reference to a parameter in the same documentation comment.| +|**\**|Specifies a reference to a type parameter in the same documentation comment.| +|**\**_text_**\**|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.| +|**\**_text_**\**|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.| -## Example +### User-defined tags -### Description +Tthe tags described above represent those that are recognized by the F# compiler and typical F# IDE tooling. However, a user is free to define their own tags. +Tools like fsdocs bring support for extra tags like [\](https://github.com/fsharp/fslang-design/blob/master/tooling/FST-1031-xmldoc-extensions.md). +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. -The following is a typical XML documentation comment in a signature file. +## Compile-time checking -### Code +For F# 5.0+, when `/warnon:3390` is enabled, the compiler verifies the syntax of the XML and the parameters referred to in `` and `` tags. -[!code-fsharp[Main](~/samples/snippets/fsharp/lang-ref-2/snippet7101.fs)] +## Documenting F# Constructs -## Example +F# constructs such as modules, members, union cases and record fields are documented by a `///` comment immediately prior to their declaration. +If needed, implicit constructors of classes are documented by giving a `///` comment prior to the argument list. For example: -### Description +```fsharp +/// This is the type +type SomeType + /// This is the implicit constructor + (a: int, b: int) = -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. + /// This is the member + member _.Sum() = a + b +``` -### Code +## Limitations -[!code-fsharp[Main](~/samples/snippets/fsharp/lang-ref-2/snippet7102.fs)] +As of F# 5.0, some features of XML documentation in C# and other .NET languages are not supported in C#. + +- In F#, cross-references must use the full XML signature of the corresponding symbol, for example . + Simple C#-style cross-references such as are not elaborated to full XML signatures + and these elements are not checked by the F# compiler. Some documentation tooling + may allow the use of these these cross-references by subsequent processing, howevr in general the full signatures should be used. + +- The tags ``, `` are not supported by the F# compiler. No error is given if they are used, but + they are simply copied to the generated documentation file without otherwise affecting the documentation generated. + +- Cross-references are not checked by the F# compiler, even when `/warnon:3390` is used. + +- The names used in the tags `` and `` are not checked by the F# compiler, even when `/warnon:3390` is used. + +- No warnings are given if documentation is missing, even when `/warnon:3390` is used. + +## Recommendations + +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. + +- Enable the option `/warnon:3390` in your code to help ensure your XML documentation is valid XML. + +- Consider adding signature files to separate long XML documentation comments from your implementation + +- For the sake of consistency, all publicly visible types and their members should be documented. If you must do it, do it all. + +- At a bare minimum, modules, types and their members should have a plain `///` comment or `` tag because its content is needed for auto-complete. + +- Documentation text should be written using complete sentences ending with full stops. ## See also +- [C# XML Documentation Comments (C# Programming Guide)](../../csharp/programming-guide/xmldoc/index.md). - [F# Language Reference](index.md) - [Compiler Options](compiler-options.md) From b6580eaa077e1db7bce66fc050e35db943df09a5 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 15 Sep 2020 14:15:41 +0100 Subject: [PATCH 02/15] Update xml-documentation.md --- .../language-reference/xml-documentation.md | 22 +++++++++++-------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/docs/fsharp/language-reference/xml-documentation.md b/docs/fsharp/language-reference/xml-documentation.md index 4a236008a95ee..a4aefe0928d06 100644 --- a/docs/fsharp/language-reference/xml-documentation.md +++ b/docs/fsharp/language-reference/xml-documentation.md @@ -36,11 +36,15 @@ You can generate the XML file at compile time by doing one of the following: - 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. -- If you are compiling a .NET application from the command line, add the [-doc compiler option](./compiler-options.md) when compiling. +- If you are compiling a .NET application from the command line, add the [-doc compiler option](./compiler-options.md) when compiling. ### Writing XML Documentation -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. +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. ## Comments without XML tags @@ -48,7 +52,7 @@ If a comment does not start with a `<` then the comment is interpreted as a `` and `&` need not be escaped. If you don't specify a summary tag explicitly, you should not specify other tags, such as **param** or **returns** tags. -The following example shows the alternative method, without XML tags. In this example, the entire text in the comment is considered a summary. +The following example shows the alternative method, without XML tags. In this example, the entire text in the comment is considered a summary. [!code-fsharp[Main](~/samples/snippets/fsharp/lang-ref-2/snippet7102.fs)] @@ -112,19 +116,19 @@ type SomeType As of F# 5.0, some features of XML documentation in C# and other .NET languages are not supported in C#. -- In F#, cross-references must use the full XML signature of the corresponding symbol, for example . - Simple C#-style cross-references such as are not elaborated to full XML signatures +- In F#, cross-references must use the full XML signature of the corresponding symbol, for example `cref="T:System.Console"`. + Simple C#-style cross-references such as `cref="Console"` are not elaborated to full XML signatures and these elements are not checked by the F# compiler. Some documentation tooling may allow the use of these these cross-references by subsequent processing, howevr in general the full signatures should be used. -- The tags ``, `` are not supported by the F# compiler. No error is given if they are used, but +- The tags ``, `` are not supported by the F# compiler. No error is given if they are used, but they are simply copied to the generated documentation file without otherwise affecting the documentation generated. - Cross-references are not checked by the F# compiler, even when `/warnon:3390` is used. -- The names used in the tags `` and `` are not checked by the F# compiler, even when `/warnon:3390` is used. +- The names used in the tags `` and `` are not checked by the F# compiler, even when `/warnon:3390` is used. -- No warnings are given if documentation is missing, even when `/warnon:3390` is used. +- No warnings are given if documentation is missing, even when `/warnon:3390` is used. ## Recommendations @@ -132,7 +136,7 @@ Documenting code is recommended for many reasons. What follows are some best pra - Enable the option `/warnon:3390` in your code to help ensure your XML documentation is valid XML. -- Consider adding signature files to separate long XML documentation comments from your implementation +- Consider adding signature files to separate long XML documentation comments from your implementation. - For the sake of consistency, all publicly visible types and their members should be documented. If you must do it, do it all. From c3aeb1918598b5557d0c4372a9f62b9df8d6f223 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 15 Sep 2020 14:19:48 +0100 Subject: [PATCH 03/15] Update xml-documentation.md --- docs/fsharp/language-reference/xml-documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/xml-documentation.md b/docs/fsharp/language-reference/xml-documentation.md index a4aefe0928d06..c168ee450fe98 100644 --- a/docs/fsharp/language-reference/xml-documentation.md +++ b/docs/fsharp/language-reference/xml-documentation.md @@ -124,7 +124,7 @@ As of F# 5.0, some features of XML documentation in C# and other .NET languages - The tags ``, `` are not supported by the F# compiler. No error is given if they are used, but they are simply copied to the generated documentation file without otherwise affecting the documentation generated. -- Cross-references are not checked by the F# compiler, even when `/warnon:3390` is used. +- Cross-references are not checked by the F# compiler, even when `/warnon:3390` is used. - The names used in the tags `` and `` are not checked by the F# compiler, even when `/warnon:3390` is used. From ecf6fc803c05120cbd7dc5846c8cf99f609b98b7 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 15 Sep 2020 18:10:11 +0100 Subject: [PATCH 04/15] Update docs/fsharp/language-reference/xml-documentation.md Co-authored-by: Phillip Carter --- docs/fsharp/language-reference/xml-documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/xml-documentation.md b/docs/fsharp/language-reference/xml-documentation.md index c168ee450fe98..eaed0f50c429c 100644 --- a/docs/fsharp/language-reference/xml-documentation.md +++ b/docs/fsharp/language-reference/xml-documentation.md @@ -114,7 +114,7 @@ type SomeType ## Limitations -As of F# 5.0, some features of XML documentation in C# and other .NET languages are not supported in C#. +Some features of XML documentation in C# and other .NET languages are not supported in C#. - In F#, cross-references must use the full XML signature of the corresponding symbol, for example `cref="T:System.Console"`. Simple C#-style cross-references such as `cref="Console"` are not elaborated to full XML signatures From 39f9270be8bda521bd65273c1e1b87b9ddfa147a Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 15 Sep 2020 18:10:20 +0100 Subject: [PATCH 05/15] Update docs/fsharp/language-reference/xml-documentation.md Co-authored-by: Phillip Carter --- docs/fsharp/language-reference/xml-documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/xml-documentation.md b/docs/fsharp/language-reference/xml-documentation.md index eaed0f50c429c..3f99dcad85ba9 100644 --- a/docs/fsharp/language-reference/xml-documentation.md +++ b/docs/fsharp/language-reference/xml-documentation.md @@ -140,7 +140,7 @@ Documenting code is recommended for many reasons. What follows are some best pra - For the sake of consistency, all publicly visible types and their members should be documented. If you must do it, do it all. -- At a bare minimum, modules, types and their members should have a plain `///` comment or `` tag because its content is needed for auto-complete. +- At a bare minimum, modules, types and their members should have a plain `///` comment or `` tag. This will show in an autocompletion tooltip window in F# editing tools. - Documentation text should be written using complete sentences ending with full stops. From 68e6da35099028edaccff26ac370c978dc0cf7c2 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 15 Sep 2020 18:10:29 +0100 Subject: [PATCH 06/15] Update docs/fsharp/language-reference/xml-documentation.md Co-authored-by: Phillip Carter --- docs/fsharp/language-reference/xml-documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/xml-documentation.md b/docs/fsharp/language-reference/xml-documentation.md index 3f99dcad85ba9..49dceb22aff96 100644 --- a/docs/fsharp/language-reference/xml-documentation.md +++ b/docs/fsharp/language-reference/xml-documentation.md @@ -89,7 +89,7 @@ The following table describes the tags for use inside description sections: ### User-defined tags -Tthe tags described above represent those that are recognized by the F# compiler and typical F# IDE tooling. However, a user is free to define their own tags. +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. Tools like fsdocs bring support for extra tags like [\](https://github.com/fsharp/fslang-design/blob/master/tooling/FST-1031-xmldoc-extensions.md). 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. From 4c51ceae862f4cf399e36af69a96f14ee68e6caa Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 15 Sep 2020 18:10:40 +0100 Subject: [PATCH 07/15] Update docs/fsharp/language-reference/xml-documentation.md Co-authored-by: Phillip Carter --- docs/fsharp/language-reference/xml-documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/xml-documentation.md b/docs/fsharp/language-reference/xml-documentation.md index 49dceb22aff96..2e4785950540c 100644 --- a/docs/fsharp/language-reference/xml-documentation.md +++ b/docs/fsharp/language-reference/xml-documentation.md @@ -64,7 +64,7 @@ If the comment body begins with `<` then it is treated as an XML formatted comme ## Recommended Tags -If using XML tags, the following table describes the outer tags recognized in F# XML code comments. +If you are using XML tags, the following table describes the outer tags recognized in F# XML code comments. |Tag syntax|Description| |----------|-----------| From a52495cc9081a3d4bc3223de638118fa86328a86 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 15 Sep 2020 18:10:48 +0100 Subject: [PATCH 08/15] Update docs/fsharp/language-reference/xml-documentation.md Co-authored-by: Phillip Carter --- docs/fsharp/language-reference/xml-documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/xml-documentation.md b/docs/fsharp/language-reference/xml-documentation.md index 2e4785950540c..ad3ce95dec845 100644 --- a/docs/fsharp/language-reference/xml-documentation.md +++ b/docs/fsharp/language-reference/xml-documentation.md @@ -119,7 +119,7 @@ Some features of XML documentation in C# and other .NET languages are not suppor - In F#, cross-references must use the full XML signature of the corresponding symbol, for example `cref="T:System.Console"`. Simple C#-style cross-references such as `cref="Console"` are not elaborated to full XML signatures and these elements are not checked by the F# compiler. Some documentation tooling - may allow the use of these these cross-references by subsequent processing, howevr in general the full signatures should be used. + may allow the use of these these cross-references by subsequent processing, but the full signatures should be used. - The tags ``, `` are not supported by the F# compiler. No error is given if they are used, but they are simply copied to the generated documentation file without otherwise affecting the documentation generated. From 821be9ccd0dd130fe5685592fd759844db39757d Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 15 Sep 2020 18:10:56 +0100 Subject: [PATCH 09/15] Update docs/fsharp/language-reference/xml-documentation.md Co-authored-by: Phillip Carter --- docs/fsharp/language-reference/xml-documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/xml-documentation.md b/docs/fsharp/language-reference/xml-documentation.md index ad3ce95dec845..8674c9f6a52a4 100644 --- a/docs/fsharp/language-reference/xml-documentation.md +++ b/docs/fsharp/language-reference/xml-documentation.md @@ -58,7 +58,7 @@ The following example shows the alternative method, without XML tags. In this ex ## Comments with XML tags -If the comment body begins with `<` then it is treated as an XML formatted comment body using XML tags. The following is a typical XML documentation comment in a signature file: +If a comment body begins with `<` then it is treated as an XML formatted comment body using XML tags. The following is a typical XML documentation comment in a signature file: [!code-fsharp[Main](~/samples/snippets/fsharp/lang-ref-2/snippet7101.fs)] From 22222615a107a1b24161936e039d499ddb32209e Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 15 Sep 2020 18:13:02 +0100 Subject: [PATCH 10/15] Update docs/fsharp/language-reference/xml-documentation.md Co-authored-by: Youssef Victor <31348972+Youssef1313@users.noreply.github.com> --- docs/fsharp/language-reference/xml-documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/xml-documentation.md b/docs/fsharp/language-reference/xml-documentation.md index 8674c9f6a52a4..dc8bfe4c55f39 100644 --- a/docs/fsharp/language-reference/xml-documentation.md +++ b/docs/fsharp/language-reference/xml-documentation.md @@ -1,7 +1,7 @@ --- title: XML Documentation description: Learn about support in F# for generating documentation from comments. -ms.date: 05/16/2016 +ms.date: 09/15/2020 --- # Document your code with XML comments From 93941bae51821bc0d6a972010aa7ce3ac05855ca Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 15 Sep 2020 18:13:19 +0100 Subject: [PATCH 11/15] Update docs/fsharp/language-reference/xml-documentation.md Co-authored-by: Youssef Victor <31348972+Youssef1313@users.noreply.github.com> --- docs/fsharp/language-reference/xml-documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/xml-documentation.md b/docs/fsharp/language-reference/xml-documentation.md index dc8bfe4c55f39..e060108a0f4d6 100644 --- a/docs/fsharp/language-reference/xml-documentation.md +++ b/docs/fsharp/language-reference/xml-documentation.md @@ -95,7 +95,7 @@ Custom or in-house documentation generation tools can also be used with the stan ## Compile-time checking -For F# 5.0+, when `/warnon:3390` is enabled, the compiler verifies the syntax of the XML and the parameters referred to in `` and `` tags. +For F# 5.0 and later, when `-warnon:3390` is enabled, the compiler verifies the syntax of the XML and the parameters referred to in `` and `` tags. ## Documenting F# Constructs From b25c40183901320f5cde54af90bb0e4e0f3d6343 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 15 Sep 2020 18:13:27 +0100 Subject: [PATCH 12/15] Update docs/fsharp/language-reference/xml-documentation.md Co-authored-by: Youssef Victor <31348972+Youssef1313@users.noreply.github.com> --- docs/fsharp/language-reference/xml-documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/xml-documentation.md b/docs/fsharp/language-reference/xml-documentation.md index e060108a0f4d6..96c27db18be2f 100644 --- a/docs/fsharp/language-reference/xml-documentation.md +++ b/docs/fsharp/language-reference/xml-documentation.md @@ -124,7 +124,7 @@ Some features of XML documentation in C# and other .NET languages are not suppor - The tags ``, `` are not supported by the F# compiler. No error is given if they are used, but they are simply copied to the generated documentation file without otherwise affecting the documentation generated. -- Cross-references are not checked by the F# compiler, even when `/warnon:3390` is used. +- Cross-references are not checked by the F# compiler, even when `-warnon:3390` is used. - The names used in the tags `` and `` are not checked by the F# compiler, even when `/warnon:3390` is used. From bcc3b9ccc1348ef83591d6ec0ded3319584e0ae3 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 15 Sep 2020 18:24:46 +0100 Subject: [PATCH 13/15] Update xml-documentation.md --- .../language-reference/xml-documentation.md | 68 ++++++++----------- 1 file changed, 30 insertions(+), 38 deletions(-) diff --git a/docs/fsharp/language-reference/xml-documentation.md b/docs/fsharp/language-reference/xml-documentation.md index 96c27db18be2f..fc3ffcd21632c 100644 --- a/docs/fsharp/language-reference/xml-documentation.md +++ b/docs/fsharp/language-reference/xml-documentation.md @@ -19,38 +19,26 @@ completeness of comments at compile-time. You can generate the XML file at compile time by doing one of the following: -- If you are developing an application with .NET Core from the command line, you can - add a `GenerateDocumentationFile` element to the `` section of your .fsproj project file. You can - also specify the path to the documentation file directly using [`DocumentationFile` element](/visualstudio/msbuild/common-msbuild-project-properties). The - following example generates an XML file in the project directory with the same root filename as the assembly: +- You can add a `GenerateDocumentationFile` element to the `` section of your `.fsproj` project file, + which generates an XML file in the project directory with the same root filename as the assembly. For example: ```xml true ``` - This is equivalent to the following: - - ```xml - bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml - ``` - - 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. -- If you are compiling a .NET application from the command line, add the [-doc compiler option](./compiler-options.md) when compiling. - ### Writing XML Documentation -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. +There are two ways to write XML documentation comments: with and without XML tags. Both use triple-slash comments. ## Comments without XML tags -If a comment does not start with a `<` then the comment is interpreted as a `` section. 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 explicitly, you should -not specify other tags, such as **param** or **returns** tags. +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. + +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 +explicitly, you should not specify other tags, such as **param** or **returns** tags. The following example shows the alternative method, without XML tags. In this example, the entire text in the comment is considered a summary. @@ -58,7 +46,11 @@ The following example shows the alternative method, without XML tags. In this ex ## Comments with XML tags -If a comment body begins with `<` then it is treated as an XML formatted comment body using XML tags. The following is a typical XML documentation comment in a signature file: +If a comment body begins with `<` (normally ``) then it is treated as an XML formatted comment +body using XML tags. This second 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 is a typical XML documentation comment in a signature file: [!code-fsharp[Main](~/samples/snippets/fsharp/lang-ref-2/snippet7101.fs)] @@ -68,24 +60,24 @@ If you are using XML tags, the following table describes the outer tags recogniz |Tag syntax|Description| |----------|-----------| -|**\**_text_**\**|Specifies that *text* is a brief description of the program element. The description is usually one or two sentences.| -|**\**_text_**\**|Specifies that *text* contains supplementary information about the program element.| -|**\**_description_**\**|Specifies the name and description for a function or method parameter.| -|**\**_description_**\**|Specifies the name and description for a type parameter.| -|**\**_text_**\**|Specifies that *text* describes the return value of a function or method.| -|**\**_description_**\**|Specifies the type of exception that can be generated and the circumstances under which it is thrown.| -|**\**|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.| +| ``**_text_**`` |Specifies that *text* is a brief description of the program element. The description is usually one or two sentences.| +| ``**_text_**`` |Specifies that *text* contains supplementary information about the program element.| +| ``**_description_**`` | Specifies the name and description for a function or method parameter.| +| ``**_description_**`` | Specifies the name and description for a type parameter.| +| ``**_text_**`` | Specifies that *text* describes the return value of a function or method.| +| ``**_description_**`` |Specifies the type of exception that can be generated and the circumstances under which it is thrown.| +| `` | 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.| The following table describes the tags for use inside description sections: |Tag syntax|Description| |----------|-----------| -|**\**_text_**\**|Specifies a paragraph of text. This is used to separate text inside the **remarks** tag.| -|**\**_text_**\**|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.| -|**\**|Specifies a reference to a parameter in the same documentation comment.| -|**\**|Specifies a reference to a type parameter in the same documentation comment.| -|**\**_text_**\**|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.| -|**\**_text_**\**|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.| +| ``**_text_**`` | Specifies a paragraph of text. This is used to separate text inside the **remarks** tag.| +| ``**_text_**`` | 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.| +| `` | Specifies a reference to a parameter in the same documentation comment.| +| `` | Specifies a reference to a type parameter in the same documentation comment.| +| ``**_text_**`` | 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.| +| ``**_text_**`` | 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.| ### User-defined tags @@ -95,7 +87,7 @@ Custom or in-house documentation generation tools can also be used with the stan ## Compile-time checking -For F# 5.0 and later, when `-warnon:3390` is enabled, the compiler verifies the syntax of the XML and the parameters referred to in `` and `` tags. +When `--warnon:3390` is enabled, the compiler verifies the syntax of the XML and the parameters referred to in `` and `` tags. ## Documenting F# Constructs @@ -126,15 +118,15 @@ Some features of XML documentation in C# and other .NET languages are not suppor - Cross-references are not checked by the F# compiler, even when `-warnon:3390` is used. -- The names used in the tags `` and `` are not checked by the F# compiler, even when `/warnon:3390` is used. +- The names used in the tags `` and `` are not checked by the F# compiler, even when `--warnon:3390` is used. -- No warnings are given if documentation is missing, even when `/warnon:3390` is used. +- No warnings are given if documentation is missing, even when `--warnon:3390` is used. ## Recommendations 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. -- Enable the option `/warnon:3390` in your code to help ensure your XML documentation is valid XML. +- Enable the option `--warnon:3390` in your code to help ensure your XML documentation is valid XML. - Consider adding signature files to separate long XML documentation comments from your implementation. From c41c1181bdb9a5a1b579c18fab76ab05e5c316d4 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 15 Sep 2020 18:26:46 +0100 Subject: [PATCH 14/15] Update xml-documentation.md --- .../language-reference/xml-documentation.md | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/fsharp/language-reference/xml-documentation.md b/docs/fsharp/language-reference/xml-documentation.md index fc3ffcd21632c..e0eb0018b2d4b 100644 --- a/docs/fsharp/language-reference/xml-documentation.md +++ b/docs/fsharp/language-reference/xml-documentation.md @@ -58,25 +58,25 @@ The following is a typical XML documentation comment in a signature file: If you are using XML tags, the following table describes the outer tags recognized in F# XML code comments. -|Tag syntax|Description| -|----------|-----------| -| ``**_text_**`` |Specifies that *text* is a brief description of the program element. The description is usually one or two sentences.| -| ``**_text_**`` |Specifies that *text* contains supplementary information about the program element.| +| Tag syntax | Description | +|---------------------------------------------|-----------| +| ``**_text_**`` | Specifies that *text* is a brief description of the program element. The description is usually one or two sentences.| +| ``**_text_**`` | Specifies that *text* contains supplementary information about the program element.| | ``**_description_**`` | Specifies the name and description for a function or method parameter.| | ``**_description_**`` | Specifies the name and description for a type parameter.| -| ``**_text_**`` | Specifies that *text* describes the return value of a function or method.| +| ``**_text_**`` | Specifies that *text* describes the return value of a function or method.| | ``**_description_**`` |Specifies the type of exception that can be generated and the circumstances under which it is thrown.| -| `` | 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.| +| `` | 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.| The following table describes the tags for use inside description sections: -|Tag syntax|Description| -|----------|-----------| -| ``**_text_**`` | Specifies a paragraph of text. This is used to separate text inside the **remarks** tag.| -| ``**_text_**`` | 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.| -| `` | Specifies a reference to a parameter in the same documentation comment.| -| `` | Specifies a reference to a type parameter in the same documentation comment.| -| ``**_text_**`` | 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.| +| Tag syntax | Description | +|-------------------------------------------|-------------| +| ``**_text_**`` | Specifies a paragraph of text. This is used to separate text inside the **remarks** tag.| +| ``**_text_**`` | 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.| +| `` | Specifies a reference to a parameter in the same documentation comment.| +| `` | Specifies a reference to a type parameter in the same documentation comment.| +| ``**_text_**`` | 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.| | ``**_text_**`` | 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.| ### User-defined tags From 5ec4fbc57c569a3ecee2d724d72a3aeaa11ce214 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 15 Sep 2020 18:27:51 +0100 Subject: [PATCH 15/15] Update xml-documentation.md --- docs/fsharp/language-reference/xml-documentation.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/fsharp/language-reference/xml-documentation.md b/docs/fsharp/language-reference/xml-documentation.md index e0eb0018b2d4b..cb55ca1caa051 100644 --- a/docs/fsharp/language-reference/xml-documentation.md +++ b/docs/fsharp/language-reference/xml-documentation.md @@ -28,8 +28,6 @@ You can generate the XML file at compile time by doing one of the following: - 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. -### Writing XML Documentation - There are two ways to write XML documentation comments: with and without XML tags. Both use triple-slash comments. ## Comments without XML tags