@@ -1,13 +1,13 @@
 ---
 title: "/experimental:module (Enable module support)"
 description: "Use the /experimental:module compiler option to enable experimental compiler support for named modules."
-ms.date: "04/13/2021"
+ms.date: 01/27/2022
 f1_keywords: ["module", "/experimental:module"]
 helpviewer_keywords: ["module", "/experimental:module", "Enable module support"]
 ---
 # `/experimental:module` (Enable module support)
 
-Enables experimental compiler support for C++ Standard modules. This option is obsolete in Visual Studio version 16.11 and later.
+Enables experimental compiler support for C++ Standard modules. This option is obsolete for C++20 standard modules in Visual Studio version 16.11 and later. It's still required (along with [`/std:c++latest`](std-specify-language-standard-version.md)) for the experimental Standard library modules.
 
 ## Syntax
 
 
@@ -1,7 +1,7 @@
 ---
 description: "Reference for header-units.json file"
 title: "C++ header unit.json reference"
-ms.date: 01/11/2022
+ms.date: 01/31/2022
 author: "tylermsft"
 ms.author: "twhitney"
 f1_keywords: ["header-units.json"]
@@ -10,16 +10,39 @@ helpviewer_keywords: ["header-units.json", "header unit"]
 
 # C++ header-units.json reference
 
-The `header-units.json` file lists which header files can be automatically built by the build system into header units, and then treated as an `import` instead of an `#include`.
+The `header-units.json` file lists which header files can be built by the build system into header units. This file must be in the same directory as the header files being included. This file is only used when [/translateInclude](translateinclude.md) is specified along with either [/scanDependencies](scandependencies.md) or [/sourceDependencies:directives]([`/sourceDependencies`](sourcedependencies.md).
 
-Sometimes a header file can't be compiled into a header unit. For example, `<cassert>` shouldn't be compiled as a header unit because it depends on a `#define` at compile time to determine its behavior. Using `#define` can't be used to change the behavior of a header unit, so `<cassert>` shouldn't be compiled into a header unit because it wouldn't provide the expected behavior.
+## Rationale
 
-When the command-line switch [`/translateInclude` (Translate include directives into import directives)](translateinclude.md) is used, the build system looks for `#include` files that can be compiled as header units.
+Some header files can't be compiled into header units. For example, given `a.h`, `b.h` and `macros.h` which are all in the same directory:
 
-There's an allowlist for the Standard Template Library (STL) headers that the build system consults when `/translateInclude` is used. The build system uses it to determine whether to create a header unit for an STL header file, and for its dependencies. If the STL header file isn't on the list, it's treated as a normal `#include` instead of importing it as a header unit.
+**a.h**
+```cpp
+#include "macros.h" // #defines MACRO=1
+#ifdef MACRO
+#include "b.h"
+#endif
+```
+
+The `header-units.json` in this directory can contain `a.h` and `b.h`, but not `macros.h`. It would look something like this:
+
+```json
+{
+    "Version": "1.0",
+    "BuildAsHeaderUnits": [
+        // macros.h should not be listed
+        "a.h",
+        "b.h"         
+     ] 
+}
+```
+
+The reason `macros.h` can't be listed in the `headerunits.json` file is that during the scan phase, the header unit (`.ifc`) may not be compiled yet for `macros.h`, so `MACRO` may not be defined whn `a.h` is compiled. That results in `b.h` missing from the list of dependencies for `a.h`, so the build system won't build a header unit for `b.h` despite it being listed in the `header-units.json` file. To avoid this problem, which results from a dependency on a macro in another header file, the header file defining the macro is excluded from the list of header files that can be compiled into a header unit.
 
 ## Schema
 
+There's a `headerunits.json` file for the Standard Template Library (STL) headers. The build system uses it to determine whether to create a header unit for an STL header file, and for its dependencies. If the STL header file isn't on the list, it's treated as a normal `#include` instead of importing it as a header unit.
+
 You can see the `header-units.json` file under the installation directory for Visual Studio. For example, `%ProgramFiles%\Microsoft Visual Studio\2022\Enterprise\VC\Tools\MSVC\14.30.30705\include\header-units.json`
 
 The `header-units.json` file starts with the schema version, followed by an array of filenames for headers that can be built into header units.
 
@@ -96,7 +96,7 @@ Expressions can use the following operators. The operators of equal precedence a
 | **`~`** | Unary one's complement. |
 | **`-`** | Unary negation. |
 |  |  |
-| **`*`*** | Multiplication. |
+| **`*`** | Multiplication. |
 | **`/`** | Division. |
 | **`%`** | Modulus (remainder). |
 |  |  |
@@ -120,7 +120,7 @@ Expressions can use the following operators. The operators of equal precedence a
 |  |  |
 | **`&&`** | Logical AND. |
 |  |  |
-| **` |  | `** | Logical OR. |
+| **` || `** | Logical OR. |
 
 > [!NOTE]
 > The bitwise XOR operator (**`^`**) is the same as the escape character, and must be escaped (as **`^^`**) when it's used in an expression.
 
@@ -1,7 +1,7 @@
 ---
 title: "/translateInclude (Translate include directives into import directives)"
 description: "Use the /translateInclude compiler option to treat #include directives as import statements when an importable header unit is available."
-ms.date: 01/28/2022
+ms.date: 01/31/2022
 author: "tylermsft"
 ms.author: "twhitney"
 f1_keywords: ["/translateInclude"]
@@ -11,7 +11,7 @@ helpviewer_keywords: ["/translateInclude", "Translate include directives into im
 
 This switch has two functions:
 * Instructs the compiler to treat `#include` as `import` for header files that have been built into header unit (`.ifc`) files and that are specified on the command line with [`/headerUnit` (Use header unit IFC)](headerunit.md).
-* When used in conjunction with [`/scanDependencies`](scandependencies.md) or [`/sourceDependencies-directives`](sourcedependencies-directives.md) and a [`header-units.json`](header-unit-json-reference.md) file (which specifies which header files can be compiled as header units), the compiler generates a JSON file that lists module and header-unit dependencies according to C++ Standard proposal [`P1689R3`](https://wg21.link/P1689r3). This dependency file is used by the build system to generate compiled header unit files (`.ifc` files). Then, instead of running the specified header files through the preprocessor, they are imported. For more details, see [Walkthrough: Build and import header units in Microsoft Visual C++](../walkthrough-header-units.md).
+* When used in conjunction with [`/scanDependencies`](scandependencies.md) or [`/sourceDependencies-directives`](sourcedependencies-directives.md), the compiler lists headers that are included both in the source and also listed in a [`header-units.json`](header-unit-json-reference.md) file as imported header units in the generated dependency file. This dependency file is used by the build system to generate compiled header unit files (`.ifc` files). Then, instead of running the specified header files through the preprocessor, they are imported. For more details, see [Walkthrough: Build and import header units in Microsoft Visual C++](../walkthrough-header-units.md).
 
 ## Syntax
 
@@ -22,7 +22,7 @@ This switch has two functions:
 `/translateInclude` is available starting in Visual Studio 2019 version 16.10.\
 The **`/translateInclude`** compiler option requires [/std:c++20](std-specify-language-standard-version.md) or a later option such as **`/std:c++latest`**.
 
-This following outlines what the Microsoft build system does when **`/translateInclude`** and `/scanDependencies` or `/sourceDependencies:directives` is specified:
+This following outlines what the Microsoft build system does when **`/translateInclude`** and [`/scanDependencies`]() or [`/sourceDependencies:directives`](sourcedependencies-directives.md) is specified:
 
 1. Get all header units and modules from referenced projects and add them, as well as their dependencies, via `/reference` and `/headerUnit` to the command line for all sources in the project.
 1. The compiler scans all of the sources that are marked to be scanned. They are marked by default based on file extension, or may be marked explicitly in the IDE. For an example of marking files explicitly, see [Walkthrough: Build and import header units in Microsoft Visual C++](../walkthrough-header-units.md).
 
@@ -61,7 +61,7 @@ If you've installed Microsoft Visual C++ Build Tools 2015 on Windows 10 or later
 
 If you're using a different version of Windows, look in your Start menu or Start page for a Visual Studio tools folder that contains a developer command prompt shortcut. You can also use the Windows search function to search for "developer command prompt" and choose one that matches your installed version of Visual Studio. Use the shortcut to open the command prompt window.
 
-Next, verify that the Visual C++ developer command prompt is set up correctly. In the command prompt window, enter `cl` and verify that the output looks something like this:
+Next, verify that the Visual C++ developer command prompt is set up correctly. In the command prompt window, enter `cl` (or `CL`, case doesn't matter for the compiler name, but it does matter for compiler options). The output should look something like this:
 
 ```Output
 C:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise>cl
 
@@ -116,19 +116,21 @@ This approach is best suited to smaller projects because it can't guarantee opti
 
 This approach combines two Visual Studio project settings:
 
-- **Scan Sources for Module Dependencies** scans your project for files and their dependencies that may be treated as header units. When combined with **Translate Includes to Imports**, header files that are specified in a `header-units.json` file are compiled into header units.
+- **Scan Sources for Module Dependencies** causes the build system to call the compiler to ensure that all imported modules and header units are built before compiling the file that depends on them.  When combined with **Translate Includes to Imports**, header files that are specified in a `header-units.json` file are also compiled into header units.
 - **Translate Includes to Imports** If an `#include` refers to a header file that can be compiled as a header unit (as specified in a `header-units.json` file), and a compiled header unit is available for the header file, then the header file is treated treated as `import`. Otherwise, it acts as a normal `#include`.
 
 You can turn on these settings in the properties for your project. To do so, right-click the project in the **Solution Explorer** and choose **Properties**:
 
 :::image type="content" source="media/vs2019-scan-module-dependencies.png" alt-text="Screenshot that shows the project properties screen with Configuration highlighted and All Configurations selected. Under C/C++ > General, Scan Sources for Module Dependencies is highlighted and set to yes, and Translate Includes to Imports is highlighted and set to Yes (/translateInclude)":::
 
+**Scan Sources for Module Dependencies option** can be set for all of the files in the project (in **Project Properties** as shown above) or for individual files in **File Properties**. Modules and header units are always scanned. Set this option is when you have a `.cpp` file that imports header units that aren't built yet and that you want to build automatically.
+
 There are conditions under which these settings work to automatically build and import header units. They are:
 
 - **Scan Sources for Module Dependencies**  scans your sources for files, and their dependencies, that may be treated as header units. Files that have the extension `.ixx`, and those which have their **File properties** > **C/C++** > **Compile As** property set to **Compile as C++ Header Unit (/export)**, are always scanned regardless of this setting. The compiler also looks for `import` statements to identify header unit dependencies. If `/translateInclude` is specified, the compiler also scans for `#include` directives that could be treated as header units. A dependency graph is built of all the modules and header units in your project.
 - **Translate Includes to Imports** When the compiler encounters an `#include` statement, and a matching header unit file (`.ifc`) exists for the specified header file, the compiler imports the header unit instead of running the header file through the preprocessor. When combined with **Scan for dependencies**, the compiler finds all of the header files that can be compiled into header units. An allow-list is consulted by the compiler to decide which header files can compile into header units. This list is stored in a [`header-units.json`](./reference/header-unit-json-reference.md) file that must be in the same directory as the included file. You can see an example of a `header-units.json` file under the installation directory for Visual Studio. For example, `%ProgramFiles%\Microsoft Visual Studio\2022\Enterprise\VC\Tools\MSVC\14.30.30705\include\header-units.json` is used by the compiler when determining whether a Standard Template Library header can be compiled into a header unit. This functionality exists to serve as a bridge with legacy code to get some benefits of header units.
 
-The `header-units.json` file serves two roles. In addition to specifying which header files can be compiled into header units, it helps minimize duplicated symbols and thus increase build throughput. For instance, given:
+The `header-units.json` file serves two roles. In addition to specifying which header files can be compiled into header units, it minimizes duplicated symbols to increase build throughput. For instance, given:
 
 ```cpp
 a.h: