improve xml documentation docs (#9096)

Author: gewarren

docs/ide/reference/generate-xml-documentation-comments.md

@@ -2,7 +2,7 @@
 title: Insert XML documentation comments
 description: Learn how to insert XML documentation comments in your code that you can use to create a compiler-generated XML file to distribute alongside your .NET assembly.
 ms.custom: SEO-VS-2020
-ms.date: 01/22/2020
+ms.date: 11/23/2021
 ms.topic: reference
 author: mikadumont
 ms.author: midumont
@@ -13,15 +13,15 @@ ms.workload:
 ---
 # How to: Insert XML comments for documentation generation
 
-Visual Studio can help you document code elements such as classes and methods, by automatically generating the standard XML documentation comment structure. At compile time, you can generate an XML file that contains the documentation comments.
+Visual Studio can help you document code elements such as classes and methods, by automatically generating the standard XML documentation comment structure. At compile time, you can generate an XML file that contains the documentation comments. To enable that option, select **Generate a file containing API documentation** on the **Build** > **Output** tab of your project's properties.
 
 > [!TIP]
-> For information about configuring the name and location of the generated XML file, see [Documenting your code with XML comments (C# Guide)](/dotnet/csharp/codedoc).
+> If you want to configure a non-default name and location for the documentation file, add the [DocumentationFile](/dotnet/core/project-sdk/msbuild-props#documentationfile) property to your *.csproj*, *.vbproj*, or *.fsproj* file.
 
 The compiler-generated XML file can be distributed alongside your .NET assembly so that Visual Studio and other IDEs can use IntelliSense to show quick information about types and members. Additionally, the XML file can be run through tools like [DocFX](https://dotnet.github.io/docfx/) and [Sandcastle](https://www.microsoft.com/download/details.aspx?id=10526) to generate API reference websites.
 
 > [!NOTE]
-> The **Insert Comment** command that automatically inserts XML documentation comments is available in [C#](/dotnet/csharp/programming-guide/xmldoc/xml-documentation-comments) and [Visual Basic](/dotnet/visual-basic/programming-guide/program-structure/how-to-create-xml-documentation). However, you can manually insert [XML documentation comments in C++](/cpp/build/reference/xml-documentation-visual-cpp) files and still generate XML documentation files at compile time.
+> The **Insert Comment** command that automatically inserts XML documentation comments is available in [C#](/dotnet/csharp/programming-guide/xmldoc/) and [Visual Basic](/dotnet/visual-basic/programming-guide/program-structure/how-to-create-xml-documentation). However, you can manually insert [XML documentation comments in C++](/cpp/build/reference/xml-documentation-visual-cpp) files and still generate XML documentation files at compile time.
 
 ## To insert XML comments for a code element
 
@@ -47,15 +47,14 @@ The compiler-generated XML file can be distributed alongside your .NET assembly
 
 You can use styles in XML comments that will render in Quick Info when hovering over the element. These styles include: italics, bold, bullets, and a clickable link.
 
-   ![Screenshot showing the completed comment with style tags for italics, bold, bullets, and a clickable link.](media/doc-style-cs.png) 
+   ![Screenshot showing the completed comment with style tags for italics, bold, bullets, and a clickable link.](media/doc-style-cs.png)
 
 > [!NOTE]
 > There is an [option](../../ide/reference/options-text-editor-csharp-advanced.md) to toggle XML documentation comments after typing `///` in C# or `'''` Visual Basic. From the menu bar, choose **Tools** > **Options** to open the **Options** dialog box. Then, navigate to **Text Editor** > **C#** or **Basic** > **Advanced**. In the **Editor Help** section, look for the **Generate XML documentation comments** option.
 
 ## See also
 
-- [XML documentation comments (C# Programming Guide)](/dotnet/csharp/programming-guide/xmldoc/xml-documentation-comments)
-- [Documenting your code with XML comments (C# Guide)](/dotnet/csharp/codedoc)
+- [Documenting your code with XML comments (C# Guide)](/dotnet/csharp/language-reference/xmldoc/)
 - [How to: Create XML documentation (Visual Basic)](/dotnet/visual-basic/programming-guide/program-structure/how-to-create-xml-documentation)
 - [C++ Comments](/cpp/cpp/comments-cpp)
 - [XML Documentation (C++)](/cpp/build/reference/xml-documentation-visual-cpp)

docs/ide/reference/options-text-editor-csharp-advanced.md

@@ -84,13 +84,13 @@ Use the **Advanced** options page to modify the settings for editor formatting,
    using System.Linq;
    ```
 
-::: moniker range=">=vs-2019"                                              
+::: moniker range=">=vs-2019"
 - Suggest usings for types in .NET Framework assemblies
 ::: moniker-end
-                                         
-::: moniker range="vs-2017"                                                
+
+::: moniker range="vs-2017"
 - Suggest usings for types in reference assemblies
-::: moniker-end                                                            
+::: moniker-end
 
 - Suggest usings for types in NuGet packages
 
@@ -132,25 +132,25 @@ Select these check boxes to display dotted vertical lines between the curly brac
 
 - Generate XML documentation comments for ///
 
-   When selected, inserts the XML elements for XML documentation comments after you type the `///` comment introduction. For more information about XML documentation, see [XML Documentation Comments (C# Programming Guide)](/dotnet/csharp/programming-guide/xmldoc/xml-documentation-comments).
+  When selected, inserts the XML elements for XML documentation comments after you type the `///` comment introduction. For more information about XML documentation, see [XML Documentation Comments (C# Programming Guide)](/dotnet/csharp/programming-guide/xmldoc/).
 
 ::: moniker range=">=vs-2019"
 
 ## Inline Hints
 
-- Inline Parameter Name Hints 
-    
-    When selected, inserts parameter name hints for literals, cast literals, and object instantiations prior to each argument in function calls.  
-    
+- Inline Parameter Name Hints
+
+    When selected, inserts parameter name hints for literals, cast literals, and object instantiations prior to each argument in function calls.
+
     ![Inline Parameter Name Hints for CSharp](media/inline-parameter-name-hints-csharp.png)
 
-- Inline Type Hints 
-    
-    When selected, inserts type hints for variables with inferred types and lambda parameter types.  
-    
+- Inline Type Hints
+
+    When selected, inserts type hints for variables with inferred types and lambda parameter types.
+
     ![Inline Type Hints for CSharp](media/inline-type-hints-csharp.png)
 
-## Inheritance Margin 
+## Inheritance Margin
 
 - When selected, adds icons to the margins representing your code's implementations and overrides. Clicking on the inheritance margin icons will display inheritance options that you can select to navigate to.
 
@@ -161,7 +161,6 @@ Select these check boxes to display dotted vertical lines between the curly brac
 ## See also
 
 - [How to: Insert XML comments for documentation generation](../../ide/reference/generate-xml-documentation-comments.md)
-- [XML Documentation Comments (C# Programming Guide)](/dotnet/csharp/programming-guide/xmldoc/xml-documentation-comments)
-- [Document your code with XML comments (C# Guide)](/dotnet/csharp/codedoc)
+- [Document your code with XML comments (C# Guide)](/dotnet/csharp/programming-guide/xmldoc/xml-documentation-comments)
 - [Set language-specific editor options](../../ide/reference/setting-language-specific-editor-options.md)
 - [C# IntelliSense](../../ide/visual-csharp-intellisense.md)