Merge pull request #10194 from MicrosoftDocs/main638484880845009781sync_temp

For protected branch, push strategy should use PR and merge to target branch method to work around git push error

Author: learn-build-service-prod[bot]

docs/ide/finding-references.md

@@ -1,7 +1,7 @@
 ---
 title: Finding references in your code
 description: Explore the Find All References command in Visual Studio to find references to particular code elements in your code, including by reference type.
-ms.date: 02/15/2023
+ms.date: 04/10/2024
 ms.topic: conceptual
 helpviewer_keywords:
 - code editor, find all references
@@ -13,30 +13,29 @@ ms.subservice: general-ide
 ---
 # Find references in your code
 
-You can use the **Find All References** command to find where particular code elements are referenced throughout your codebase. The **Find All References** command is available on the context (right-click) menu of the element you want to find references to. Or, if you're a keyboard user, press **Shift + F12**.
+You can use the **Find All References** command to find where particular code elements are referenced throughout your codebase. The **Find All References** command is available on the context (right-click) menu of the element you want to find references to. Or, press **Alt + F2**.
 
 The results appear in a tool window named **\<element> references**, where *element* is the name of the item you're searching for. A toolbar in the **references** window enables you to do the following:
 
-- Change the scope of the search in a drop-down list box. You can choose to look only in changed documents all the way up to the entire solution.
-- Copy the selected referenced item by choosing the **Copy** button.
-- Choose buttons to go to the next or previous location in the list, or press the **F8** and **Shift + F8** keys to do so.
+- Change the scope of the search in a drop-down list box. You can choose to look only in open or changed documents, all the way up to the entire solution.
+- Copy the selected referenced item(s) by choosing the **Copy** button. All the values in all the columns for all selected rows are copied to the clipboard, preceded by the column headings. This makes it easy to paste into a spreadsheet.
+- Choose buttons to go to the next or previous location in the list, or press the up and down arrow keys to do so.
 - Remove any filters on the returned results by choosing the **Clear All Filters** button.
 - Change how returned items are grouped by choosing a setting in the **Group by:** drop-down list box.
 - Keep the current search results window by choosing the **Keep Results** button. When you choose this button, the current search results stay in this window, and new search results appear in a new tool window.
 - Search for strings within the search results by entering text in the **Search Find All References** text box.
 
-You can also hover the mouse over any search result to see a preview of the reference.
+You can also hover the mouse over any search result to see the reference in the context of the surrounding code.
 
 ![Screenshot of the Find All References tool window.](../ide/media/vside_findallreferences.png)
 
 ## Navigate to references
 
 You can use the following methods to navigate to references in the **references** window:
 
-- Press **F8** to go to the next reference, or **Shift + F8** to go to the previous reference.
 - Press the **Enter** key on a reference, or double-click it, to go to it in code.
 - On the right-click menu (context menu) of a reference, choose the **Go To Previous Location** or **Go To Next Location** commands.
-- Choose the **Up Arrow** and **Down Arrow** keys (if they're enabled in the **Options** dialog box). To enable this functionality, on the menu bar, choose **Tools** > **Options** > **Environment** > **Tabs and Windows**, and then in the **Preview Tab** section, select the **Allow new files to be opened in the preview tab** and **Preview selected files in Find Results** boxes.
+- Use the **Up Arrow** and **Down Arrow** keys.
 
 ## Change reference groupings
 
@@ -52,6 +51,10 @@ In C# or Visual Basic, the **Find References** window has a **Kind** column wher
 
 After you apply a filter or a filter set, you can easily remove it by using the **Clear All Filters** button.
 
+## Customize the experience
+
+To customize the experience, on the menu bar, choose **Tools** > **Options** > **Environment** > **Tabs and Windows**, and then in the **Preview Tab** section, if you select the **Allow new files to be opened in the preview tab** checkbox, you can select or unselect the **Preview selected files in Find Results** checkbox. When selected, the file is opened in the editor at the place where the reference occurs. When unset, the file is only opened if you explicitly press **Enter** or double-click on the row.
+
 ## Related content
 
 - [Navigating code](../ide/navigating-code.md)

docs/ide/media/code-snippet-description-author.png

@@ -1,58 +1,123 @@
 ---
 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.date: 11/23/2021
-ms.topic: reference
+description: Learn how to insert XML documentation comments in your code and create a compiler-generated XML comments file to distribute with your .NET assembly.
+ms.date: 04/11/2024
+ms.topic: how-to
 author: mikadumont
 ms.author: midumont
 manager: mijacobs
 ms.subservice: general-ide
 ---
 # 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. To enable that option, select **Generate a file containing API documentation** on the **Build** > **Output** tab of your project's properties.
+This article describes how 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.
 
-> [!TIP]
-> 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.
+You can distribute the compiler-generated XML file along with your .NET assembly so that Visual Studio and other IDEs can use IntelliSense to show quick information about types and members. You can also run the XML file 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/) 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
-
-1. Place your text cursor above the element you want to document, for example, a method.
-
-2. Do one of the following:
-
-   - Type `///` in C#, or `'''` in Visual Basic
-
-   - From the **Edit** menu, choose **IntelliSense** > **Insert Comment**
-
-   - From the right-click or context menu on or just above the code element, choose **Snippet** > **Insert Comment**
-
-   The XML template is immediately generated above the code element. For example, when commenting a method, it generates the **\<summary\>** element, a **\<param\>** element for each parameter, and a **\<returns\>** element to document the return value.
-
-   ![XML comment template - C#](media/doc-preview-cs.png)
-
-   ![XML comment template - Visual Basic](media/doc-preview-vb.png)
-
-3. Enter descriptions for each XML element to fully document the code element.
-
-   ![Screenshot showing the completed comment.](media/doc-result-cs.png)
-
-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)
-
-> [!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 **Visual Basic**) > **Advanced**. In the **Editor Help** section, look for the **Generate XML documentation comments** option.
-
-## See also
+> The **Insert Comment** command to automatically insert XML documentation comment structure is available in [C#](/dotnet/csharp/programming-guide/xmldoc/) and [Visual Basic](/dotnet/visual-basic/programming-guide/program-structure/how-to-create-xml-documentation). For C++, you can [manually insert XML documentation comments](/cpp/build/reference/xml-documentation-visual-cpp) and still generate XML documentation files at compile time.
 
-- [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)
-- [Code generation](../code-generation-in-visual-studio.md)
+## Enable documentation generation
+
+   ::: moniker range=">= vs-2022"
+To enable documentation generation, select the **Generate a file containing API documentation** checkbox on the **Build** > **Output** tab of your project's properties.
+
+By default, a documentation file named the same as your assembly with an *.xml* file extension generates in the same directory as the assembly. If you want to configure a nondefault name or location for the  file, enter or browse to an alternate location under **XML documentation file path**.
+   ::: moniker-end
+
+   ::: moniker range="<= vs-2019"
+To enable documentation generation, select the **XML documentation file** checkbox in the **Build** > **Output** section of your project's properties.
+
+By default, a documentation file named the same as your assembly with an *.xml* file extension generates in the same directory as the assembly. If you want to configure a nondefault name or location for the  file, enter or browse to an alternate location.
+   ::: moniker-end
+
+Alternatively, you can add the [GenerateDocumentationFile](/dotnet/core/project-sdk/msbuild-props#generatedocumentationfile) or [DocumentationFile](/dotnet/core/project-sdk/msbuild-props#documentationfile) properties to your *.csproj*, *.vbproj*, or *.fsproj* file. Set `GenerateDocumentationFile` to `true` to generate a documentation file with the default name and location. Use the `DocumentationFile` property to specify a different name or location.
+
+If you use `DocumentationFile` by itself or with the `GenerateDocumentationFile` property set to `true`, a documentation file with the specified name and location is generated. However, if you set `GenerateDocumentationFile` to `false`, no documentation file is generated even if you set the `DocumentationFile` property.
+
+## Enable comment insertion keyboard shortcut
+
+You can set the [Comments](options-text-editor-csharp-advanced.md#comments) option to automatically insert XML comment structures after you type `///` in C# or `'''` in Visual Basic.
+
+1. From the Visual Studio menu bar, choose **Tools** > **Options**.
+1. In the **Options** dialog box, navigate to **Text Editor** > **C#** (or **Visual Basic**) > **Advanced**.
+1. Under the **Comments** section, select or deselect **Generate XML documentation comments for \\\\\\** (or **'''**).
+
+## Automatically insert an XML comment
+
+1. In Visual Studio, place your cursor above the element you want to document, for example a method.
+
+1. Take one of the following actions:
+
+   - If the automatic comment insertion shortcut is enabled, type `///` in C#, or `'''` in Visual Basic.
+   - From the **Edit** menu, choose **IntelliSense** > **Insert Comment**.
+   - From the right-click or context menu, choose **Snippet** > **Insert Comment**.
+
+   The XML comment structure is immediately generated above the code element. For example, when commenting the following `GetUserName` method, the template generates the `<summary>` element, a `<param>` element for the parameter, and a `<returns>` element to document the return value.
+
+    ```csharp
+    /// <summary>
+    /// 
+    /// </summary>
+    /// <param name="id"></param>
+    /// <returns></returns>
+    public string GetUserName(int id)
+    {
+        return "username";
+    }
+    ```
+
+    ```vb
+    ''' <summary>
+    ''' 
+    ''' </summary>
+    ''' <param name="id"></param>
+    ''' <returns></returns>
+    Public Function GetUserName(id As Integer) As String
+        Return "username"
+    End Function
+    ```
+
+1. Enter descriptions for each XML element to fully document the code. For example:
+
+   ```csharp
+    /// <summary>
+    /// Gets the username associated with the specified ID.
+    /// </summary>
+    /// <param name="id">The unique user ID.</param>
+    /// <returns>A string containing the username for the specified ID.</returns>
+    public string GetUserName(int id)
+    {
+        return "username";
+    }
+   ```
+You can use XML elements and styles in comments that render in Quick Info when you hover over the code. These elements include italic or bold styles, bulleted or numbered lists, and clickable `cref` or `href` links.
+
+For example, enter the following code into a C# program file:
+
+```csharp
+/// <summary>
+/// There are two <see href="https://bing.com">params</see>.
+/// <list type="number">
+/// <item><param name="id">The user <em>id</em></param></item>
+/// <item><param name="username">The user <em>name</em></param></item>
+/// </list>
+/// </summary>
+/// <returns>The <strong>username</strong>.</returns>
+public static string GetUserName(int id)
+{
+    return "username";
+}
+```
+
+When you hover over **GetUserName**, the Quick Info pane appears as follows:
+
+![Screenshot showing the completed comment with style tags for a clickable link, a numbered list, and italic and bold formatting.](media/doc-style-cs.png)
+
+## Related content
+
+- [Documentation comments](/dotnet/csharp/language-reference/xmldoc/)
+- [XML documentation in Visual Basic](/dotnet/visual-basic/programming-guide/program-structure/how-to-create-xml-documentation)
+- [Comments (C++)](/cpp/cpp/comments-cpp)
+- [XML Documentation (Visual C++)](/cpp/build/reference/xml-documentation-visual-cpp)
+- [Code generation](../writing-code-in-the-code-and-text-editor.md#generate-fix-or-refactor-code)