Repo sync for protected branch

docs/ide/include-cleanup-config.md

@@ -0,0 +1,67 @@
+---
+title: "Configure C/C++ Include Cleanup in Visual Studio"
+description: "Learn how to configure C/C++ Include Cleanup."
+ms.date: 10/10/2023
+ms.topic: "how-to"
+f1_keywords: ["config include cleanup"]
+helpviewer_keywords: ["config include cleanup"]
+---
+# Configure C/C++ Include Cleanup in Visual Studio
+
+Starting with 17.8 Preview 1, Visual Studio can clean up your `#include`s to improve the quality of your C and C++ code in the following ways:
+- Offers to add header files for code that compiles only because a needed header file is included indirectly by another header file.
+- Offers to remove unused header files--improving build times.
+
+This article describes how to configure Include Cleanup in Visual Studio. For more information about Include Cleanup, see [C/C++ Include Cleanup overview](include-cleanup-overview.md).
+
+## Turn on Include Cleanup
+
+The Include Cleanup feature is on by default. If it isn't active, you can turn it on via **Tools** > **Options** > **Text Editor** > **C/C++** > **Code Cleanup** and select **Enable #include cleanup**.
+
+Then use the dropdowns to configure how you want to be notified about opportunities to add indirect headers or remove unused headers:
+
+:::image type="complex" source="media/vs2022-include-cleanup-option.png" alt-text="The Tools options dialog opened at Text Editor > C/C++ > Code Cleanup.":::
+The Enable # include cleanup checkbox is checked. The dropdowns for Remove unused includes suggestion level, and Add missing includes suggestion level, are shown. The contents of the dropdown are shown, which are: **Refactoring only**, **Suggestion**, **Warning**, and **Error**. The **Remove unused includes suggestion level** dropdown offers the same options but also adds dimmed.
+:::image-end:::
+
+The meanings of the suggestion level options are:
+
+**Refactoring only**: Include Cleanup offers actions you can take through the quick action menu when you hover the mouse pointer over an `#include`, or place the cursor on the `#include` line and press Ctrl+period:
+
+:::image type="complex" source="media/include-cleanup-refactor-lightbulb.png" alt-text="A screenshot of the quick action to remove an unused header":::
+When hovering the cursor over # include iostream, a light bulb appears with the text that # include iostream isn't used in this file."
+:::image-end:::
+
+**Suggestion, Warning, Error**: Include Cleanup offers actions it can take via suggestions, warnings, or errors in the Error List window. You determine which. In the following screenshot of the Error List, Include Cleanup is configured to show unused headers with a warning. Ensure that **Build + Intellisense** is selected in the dropdown filter so that you can see the Include Cleanup output:
+
+:::image type="complex" source="media/include-cleanup-error-list.png" alt-text="A screenshot of the Error List window.":::
+The dropdown filter is set to Build + IntelliSense. A warning is visible: VCIC002 - #include < iostream > isn't used in this file."
+:::image-end:::
+
+**Dimmed**
+
+Include Cleanup shows unused headers by dimming the line of the unused header file in the code editor. Hover your cursor over the dimmed `#include` to bring up the quick action menu and choose **Show potential fixes**, or click on the light bulb dropdown, to see actions related to the unused file.
+
+:::image type="complex" source="media/include-cleanup-dimmed-include.png" alt-text="A screenshot of a dimmed #include < iostream > line.":::
+The line for #include < iostream > is dimmed because the line of code that uses iostream is commented out. That line of code is // std::cout << "charSize = " << charSize; The quick action menu is also visible for this line. It says the #include < iostream > isn't used in this file, and has a link to Show potential fixes.
+:::image-end:::
+
+## Configure Include Cleanup with `.editorconfig`
+
+There are more options for configuring Include Cleanup such as excluding specified includes from cleanup suggestions, indicating that some header files are required so that the tool doesn't mark them as unused, and so on. These options are defined in an `.editorconfig` file, that you can add to your project to, among other things, enforce consistent coding styles for everyone that works in the codebase. For more information about adding an `.editorconfig` file to your project, see [Create portable, custom editor settings with EditorConfig](/visualstudio/ide/create-portable-custom-editor-options).
+
+The `.editorconfig` settings that you can use with Include Cleanup are:
+
+| Setting | Values | Example |
+|--|--|--|--|
+| `cpp_include_cleanup_add_missing_error_tag_type`</br></br>Sets the error level of add transitive include messages. | `none`</br>`suggestion`</br>`warning`</br>`error` | `cpp_include_cleanup_add_missing_error_tag_type = suggestion` |
+| `cpp_include_cleanup_remove_unused_error_tag_type`</br></br>Sets the error level of remove unused include messages. | `none`</br>`suggestion`</br>`warning`</br>`error`</br>`dimmed` | `cpp_include_cleanup_remove_unused_error_tag_type = dimmed` |
+| `cpp_include_cleanup_excluded_files`</br></br>Excludes the specified files from Include Cleanup messages. You won’t get a suggestion related to the header at all, whether to add it or that it's unused. | *filename* | `cpp_include_cleanup_excluded_files = vcruntime.h, vcruntime_string.h` |
+| `cpp_include_cleanup_required_files`</br></br>Specify that usage of *file1* requires *file2*. For example, specify that if you use `atlwin.h` that `altbase.h` must also be included. | *file1*:*file2* | `cpp_include_cleanup_required_files = atlwin.h:altbase.h, atlcom.h:altbase.h` |
+| `cpp_include_cleanup_replacement_files`</br></br>Replaces *file1* with *file2* during Include Cleanup processing. For example, you may prefer using `cstdio` over `stdio.h`. If you have a file with both `#include <cstudio>` and `#include <stdio.h>` and you consume content only from `stdio.h`, with this setting Include Cleanup will tell you to remove `stdio.h` because it replaced the usage of `cstdio` with `stdio.h` during processing. If you don't use the contents from either, Include Cleanup will tell you to remove both.| *file1*:*file2* | `cpp_include_cleanup_replacement_files = stdio.h:cstdio,stdint.h:cstdint` |
+| `cpp_include_cleanup_alternate_files`</br></br>Don't generate a message for indirect include *file2* if *file1* is included. For example, if you `#include <windows.h>` and are only using something from its indirectly included header `winerror.h`, Include Cleanup won't prompt to add `winerror.h`. Useful when you prefer to include a facade header file instead of the indirect includes it contains. | *file1*:*file2* | `cpp_include_cleanup_alternate_files = windows.h:winerror.h, windows.h:minwindef.h` |
+
+## See also
+
+[C/C++ Include Cleanup overview](include-cleanup-overview.md)\
+[Include Cleanup messages](include-cleanup-messages.md)

docs/ide/include-cleanup-messages.md

@@ -0,0 +1,41 @@
+---
+title: "Include Cleanup messages"
+description: "Learn what the messages generated by Include Cleanup mean."
+ms.date: 10/10/2023
+ms.topic: "reference"
+f1_keywords: ["VCIC001", "VCIC002"]
+helpviewer_keywords: ["VCIC001", "VCIC002"]
+---
+# Include Cleanup messages
+
+This article describes the messages generated by the Include Cleanup feature. For more information about Include Cleanup, see [C/C++ Include Cleanup overview](include-cleanup-overview.md).
+
+Starting with 17.8 Preview 1, Visual Studio can clean up your `#include`s to improve the quality of your C and C++ code in the following ways:
+
+- Offers to add header files for code that compiles only because a needed header file is included indirectly by another header file.
+- Offers to remove unused header files--improving build times.
+
+You can choose whether messages from Include Cleanup appear in the form of suggestions, warnings, or errors in the Error List window. For more information, see [Config C/C++ Include Cleanup in Visual Studio](include-cleanup-config.md).
+
+In the following screenshot of the Error List, Include Cleanup is configured to show unused headers with a warning:
+
+:::image type="complex" source="media/include-cleanup-error-list.png" alt-text="A screenshot of the Error List window.":::
+The dropdown filter is set to Build + IntelliSense. A warning is visible: VCIC002 - #include < iostream > isn't used in this file."
+:::image-end:::
+
+Include Cleanup generates the following messages:
+
+## `VCIC001`: Content from #include is used in this file and transitively included
+
+This message means that you're using content from a header file that is included indirectly.
+
+For example, you may be directly including a header file that also contains `#include <string>`. If you use `string` in your code, but don't `#include <string>` in that file, it works as long as the other header file continues to indirectly include `<string>` for you. This message identifies this situation in your code so that you can take action to directly include the transitively included header file. For more information, see [Direct vs indirect headers](include-cleanup-overview.md#direct-vs-indirect-headers).
+
+## `VCIC002`: #include is not used in this file
+
+This message means that the specified header file is not used in the current file. You can remove the associated `#include` directive to clean up your `#include`s and improve your build times.
+
+## See also
+
+[C/C++ Include Cleanup overview](include-cleanup-overview.md)\
+[Configure C/C++ Include Cleanup in Visual Studio](include-cleanup-config.md)

docs/ide/include-cleanup-overview.md

@@ -0,0 +1,125 @@
+---
+title: "Clean up C/C++ #includes in Visual Studio"
+description: "Learn about using C/C++ Include Cleanup in Visual Studio to remove unused headers, and transitively add indirect headers needed in your project."
+ms.date: 10/5/2023
+ms.topic: "overview"
+ms.custom: intro-overview
+f1_keywords: ["include cleanup"]
+helpviewer_keywords: ["include cleanup"]
+---
+# Clean up C/C++ includes in Visual Studio
+
+Starting with Visual Studio 17.8 Preview 1, Visual Studio provides an `#include` cleanup feature that improves the quality of your code in the following ways:
+
+- Offers to add header files for code that compiles only because a needed header file is included indirectly by another header file.
+- Offers to remove unused header files--improving build times and code cleanliness.
+
+Include Cleanup is on by default. To learn how to configure it, see [Config C/C++ Include Cleanup in Visual Studio](include-cleanup-config.md).
+
+## Direct vs indirect headers
+
+First some terminology:
+
+- A direct header is a header that you explicitly `#include` in your code.
+- An indirect header is a header that you don't explicitly `#include`. Instead, a header file that you do directly include, includes it. We also say that an indirect header is included `transitively`.
+
+Include Cleanup analyzes your code and determines which headers aren't used and which are indirectly included. Consider the following header file:
+
+```cpp
+// myHeader.h
+
+#include <string>
+#include <iostream>
+
+void myFunc()
+{
+    std::string s = "myFunc()\n";
+    std::cout << s;
+}
+```
+
+And the program that uses it:
+
+```cpp
+// myProgram.cpp
+#include "myHeader.h"
+
+int main()
+{
+    std::string s = "main()"; // string is indirectly included by myHeader.h
+    std::cout << s; // cout is indirectly included by myHeader.h
+    myFunc();
+}
+```
+
+`myHeader.h` is a direct header because `myProgram.cpp` explicitly includes it. `myHeader.h` includes `<string>` and `<iostream>`, so those are indirect headers.
+
+The issue is that `myProgram.cpp` uses `std::string` and `std::cout`, but doesn't directly include the headers that define them. This code happens to compile because `myHeader.h` includes those headers. This code is brittle because if `myHeader.h` ever stopped including either one, `myProgram.cpp` wouldn't compile anymore.
+
+Per the C++ guidelines, it's better to explicitly include headers for all of your dependencies so that your code isn't subject to brittleness caused by changes to header files. For more information, see [C++ Core Guidelines SF.10](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#sf10-avoid-dependencies-on-implicitly-included-names).
+
+Include Cleanup analyzes your code to identify unused and indirectly included headers. It provides feedback based on the settings described in [Config the C++ #include tool in Visual Studio](include-cleanup-config.md). Feedback can be in the form of error list warnings, suggestions, etc. For more details on the feedback provided by Include Cleanup, refer [Include Cleanup messages](include-cleanup-messages.md).
+
+## Unused headers
+
+As your code evolves, you may no longer need some header files. This is hard to keep track of in a complex project. Over time, your builds may take longer because the compiler is processing unnecessary header files. Include Cleanup helps you find and remove unused headers. For example, what if `myFunc()` is commented out in `myProgram.cpp`:
+
+```cpp
+// myProgram.cpp
+#include "myHeader.h"
+
+int main()
+{
+    std::string s = "main()"; // string is indirectly included from myHeader.h
+    std::cout << s; // cout is indirectly included from myHeader.h
+    // myFunc(); // directly included from myHeader.h
+}
+```
+
+In the following screenshot, `#include "myHeader.h"` is dimmed (a setting described in [Config the C++ #include tool in Visual Studio](include-cleanup-config.md)) because it isn't used since `myFunc()` is commented out.
+
+Hover your cursor over the dimmed `#include` to bring up the quick action menu. Click the light bulb (or choose the **Show potential fixes** link) to see actions related to the unused file:
+
+:::image type="content" source="media/vs2022-include-cleanup-refactor-options.png" alt-text="Three refactoring options are shown: Remove # include myHeader.h, remove all unused includes, and Add all transitively used and remove all unused # includes.":::
+
+## Add transitively used headers
+
+We could choose to remove the unused header file, but that breaks the code since `<string>` and `<iostream>` are indirectly included via `myheader.h`.
+
+Instead, we can choose **Add all transitively used and remove all unused #includes**. This removes the unused header `myHeader.h`, but also adds any headers being used that are indirectly included via `myHeader.h`. The result, in this case, is adding `#include <string>` and `#include <iostream>` to `myProgram.cpp`, and removing `#include "myHeader.h"`:
+
+```cpp
+// myProgram.cpp
+#include <iostream>
+#include <string>
+
+int main()
+{
+    std::string s = "main()"; // string is directly included from <string>
+    std::cout << s; // cout is directly included from <string>
+    // MyFunc();
+}
+```
+
+The tool doesn't update the comments, but you can see that the code is now using `std::string` and `std::cout` directly. This code is no longer brittle because it doesn't depend on `myHeader.h` to include the other required headers.
+
+## Best practice
+
+Don't remove what appear to be unused header files without first adding indirectly included header files. That's because your code may rely on indirect includes in a header file that is otherwise unused. Add transitively used headers first. Then, when you remove unused headers, you don't get compilation errors due to missing header files that are included indirectly by a header file you've removed.
+
+One way to do this is to set the Include Cleanup setting for **Add missing includes suggestion level** to **Suggestion** (**Tools** > **Options** > **Text Editor** > **C/C++** > **Code Cleanup**). Also set **Remove unused includes suggestion level** to **Suggestion**. Then:
+
+1. In the error list, make sure the filter is set to **Build + IntelliSense**.
+1. Look for instances of "Content from #include x is used in this file and transitively included."
+1. Hover your cursor over a line with the suggestion. From the light bulb dropdown, select **Add all transitively used includes**.
+1. Repeat these steps in your project until all suggestions regarding transitive includes are addressed.
+1. Remove unused includes: in the error list, look for an instance of "#include x is not used in this file."
+1. Hover your cursor over the unused header. From the light bulb dropdown, select **Remove all unused includes**.
+1. Repeat these steps in your project until all Include Cleanup suggestions are addressed.
+
+In this brief overview, you've seen how Include Cleanup can help you remove unused headers, and add headers that were indirectly included. This helps you keep your code clean, potentially build faster, and reduces the brittleness of your code.
+
+## See also
+
+[Configure C/C++ Include Cleanup in Visual Studio](include-cleanup-config.md)\
+[Include Cleanup messages](include-cleanup-messages.md)

docs/ide/toc.yml

@@ -8,6 +8,12 @@ items:
       href: ../ide/writing-and-refactoring-code-cpp.md
     - name: Navigate C++ code
       href: ../ide/navigate-code-cpp.md
+    - name: C/C++ Include Cleanup overview
+      href: ../ide/include-cleanup-overview.md
+    - name: Configure C/C++ Include Cleanup
+      href: ../ide/include-cleanup-config.md
+    - name: Include Cleanup messages
+      href: ../ide/include-cleanup-messages.md
     - name: Set your C++ coding preferences
       href: ../ide/how-to-set-preferences.md
     - name: Collaborate using Live Share for C++