8/6/2021 AM Publish (#3707)

* fix code sample (#3676)

* fix code sample

* acrolinx

Co-authored-by: TylerMSFT <[email protected]>

* Address 3269 typo in warning number (#3680)

* Fixed typo: evalution --> evaluation

* Bulk Fix - Sentence form for all alt text (#3683)

* Updated C/C++ workload name

The workload for C/C++ development in VS Build Tools 2019 installer is called 'Desktop development with C++'.

* Split out docs by version

Add VS2017-specific instructions.

* Add 16.11 Compiler Warnings C5247 and C5248 (MicrosoftDocs#3689)

* Add C5247 and C5248

* Fix link typos

* Updates per Xiang Fan review

* More wordsmithage

* More fix per X.F.

* Fix inconsistencies in CMake docs (MicrosoftDocs#3692)

* Standard format for CMake docs

* Fix markdownlint

* More cleanup.

* Clean up link issue, acrolinx

* Fix more broken things

* Undo a change

* Update markdownlint.json file for unordered lists (#3694)

Block rule that wants * instead of - to prefix unordered lists, since we've standardized on the latter.

Merging on my own recognizance as repo admin.

* Markdown quality fixes 1 of N

* Markdown quality fixes 2 of N

* Markdown quality fixes 3 of N

* Markdown quality fixes 4 of N

* Markdown quality fixes 5 of N

* Markdown quality fixes 6 of N

* Markdown quality fixes 7 of N

* Markdown quality fixes 8 of N

* Markdown quality fixes 9 of N

* Markdown quality fixes 10 of N

* Undo TN038

* Markdown quality fixes 11 of N

Co-authored-by: Tyler Whitney <[email protected]>
Co-authored-by: TylerMSFT <[email protected]>
Co-authored-by: Colin Robertson <[email protected]>
Co-authored-by: ystamant <[email protected]>
Co-authored-by: Andrew Shymanel <[email protected]>
Co-authored-by: PRMerger6 <[email protected]>
Co-authored-by: PRMerger12 <[email protected]>
Co-authored-by: PRMerger14 <[email protected]>
Co-authored-by: PRMerger16 <[email protected]>
Co-authored-by: PRMerger15 <[email protected]>
Co-authored-by: PRMerger7 <[email protected]>
Co-authored-by: PRMerger10 <[email protected]>

Author: 13 people

docs/atl-mfc-shared/reference/coledatetime-class.md

@@ -128,12 +128,10 @@ The `COleDateTime` object to be compared.
 > [!NOTE]
 > An ATLASSERT will occur if either of the two operands is invalid.
 
-### Example
+### Examples
 
 [!code-cpp[NVC_ATLMFC_Utilities#13](../../atl-mfc-shared/codesnippet/cpp/coledatetime-class_2.cpp)]
 
-### Example
-
 The operators **>=**, **\<=**, **>**, and **<**, will assert if the `COleDateTime` object is set to null.
 
 [!code-cpp[NVC_ATLMFC_Utilities#170](../../atl-mfc-shared/codesnippet/cpp/coledatetime-class_3.cpp)]

docs/atl-mfc-shared/reference/crect-class.md

@@ -396,7 +396,7 @@ BOOL EqualRect(LPCRECT lpRect) const throw();
 ### Parameters
 
 *`lpRect`*<br/>
-Points to a [`RECT](/windows/win32/api/windef/ns-windef-rect) structure or `CRect` object that contains the upper-left and lower-right corner coordinates of a rectangle.
+Points to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or `CRect` object that contains the upper-left and lower-right corner coordinates of a rectangle.
 
 ### Return Value
 

docs/atl-mfc-shared/reference/csimplestringt-class.md

@@ -337,8 +337,6 @@ _tprintf_s(_T("Alloc length is %d, String length is %d\n"),
    str.GetAllocLength(), str.GetLength());
 ```
 
-### Remarks
-
 The output from this example is as follows:
 
 ```Output

docs/atl/programming-with-ccombstr-atl.md

@@ -27,9 +27,7 @@ Although several `CComBSTR` methods will automatically convert an ANSI string ar
 
 [!code-cpp[NVC_ATL_Utilities#114](../atl/codesnippet/cpp/programming-with-ccombstr-atl_1.cpp)]
 
-If you are using a string literal to modify a `CComBSTR` object, use wide character strings. This will reduce unnecessary conversions.
-
-### Example
+If you're using a string literal to modify a `CComBSTR` object, use wide character strings to reduce unnecessary conversions.
 
 [!code-cpp[NVC_ATL_Utilities#115](../atl/codesnippet/cpp/programming-with-ccombstr-atl_2.cpp)]
 

docs/atl/reference/cwindow-class.md

@@ -874,9 +874,7 @@ BOOL GetDlgItemText(
 
 ### Remarks
 
-See [GetDlgItemText](/windows/win32/api/winuser/nf-winuser-getdlgitemtextw) in the Windows SDK.
-
-### Remarks
+For more information, see [`GetDlgItemText`](/windows/win32/api/winuser/nf-winuser-getdlgitemtextw) in the Windows SDK.
 
 The second version of this method allows you to copy the control's text to a BSTR. This version returns TRUE if the text is successfully copied; otherwise, FALSE.
 
@@ -1209,9 +1207,7 @@ LONG_PTR GetWindowLongPtr(int nIndex) const throw();
 
 ### Remarks
 
-See [GetWindowLongPtr](/windows/win32/api/winuser/nf-winuser-getwindowlongptrw) in the Windows SDK.
-
-### Remarks
+For more information, see [`GetWindowLongPtr`](/windows/win32/api/winuser/nf-winuser-getwindowlongptrw) in the Windows SDK.
 
 If you are retrieving a pointer or a handle, this function supersedes the `CWindow::GetWindowLong` method.
 
@@ -1429,9 +1425,7 @@ void InvalidateRgn(HRGN hRgn, BOOL bErase = TRUE) throw();
 
 ### Remarks
 
-See [InvalidateRgn](/windows/win32/api/winuser/nf-winuser-invalidatergn) in the Windows SDK.
-
-### Remarks
+For more information, see [`InvalidateRgn`](/windows/win32/api/winuser/nf-winuser-invalidatergn) in the Windows SDK.
 
 Specifies a **`void`** return type, while the `InvalidateRgn` Win32 function always returns TRUE.
 

docs/build/reference/headername.md

@@ -36,20 +36,20 @@ If you specify **`/headerName:{quote,angle}`**, you must also specify [`/exportH
 Given a project that references a header file it defines called `m.h`, the compiler option to compile it into a header unit looks similar to this:
 
 ```Bash
-$ cl /std:c++latest /exportHeader /headerName:quote m.h /Fom.h.obj
+cl /std:c++latest /exportHeader /headerName:quote m.h /Fom.h.obj
 ```
 
 The `/headerName:{quote,angle}`switch acts like a flag and does not explicitly need an argument. The following examples are valid:
 
 ```Bash
-$ cl /std:c++latest /exportHeader /headerName:angle /MP /Fo.\ vector iostream algorithm
-$ cl /std:c++latest /exportHeader /headerName:quote /MP /Fo.\ my-utilities.h a/b/my-core.h
+cl /std:c++latest /exportHeader /headerName:angle /MP /Fo.\ vector iostream algorithm
+cl /std:c++latest /exportHeader /headerName:quote /MP /Fo.\ my-utilities.h a/b/my-core.h
 ```
 
 You can specify multiple `/headerName` switches on the same command line, and every argument after that switch will be processed with the specified *`header-filename`* lookup rules. The following example processes all the headers as the previous two command line examples in the same way. It looks up the headers using the lookup rules applied as if they had been specified as: `#include <vector>`, `#include "my-utilties.h"`, and `#include "a/b/my-core.h"`:
 
 ```bash
-$ cl /std:c++latest /exportHeader /headerName:angle /MP /Fo.\ vector iostream algorithm /headerName:quote my-utilities.h a/b/my-core.h
+cl /std:c++latest /exportHeader /headerName:angle /MP /Fo.\ vector iostream algorithm /headerName:quote my-utilities.h a/b/my-core.h
 ```
 
 ### To set this compiler option in the Visual Studio development environment

docs/build/reference/module-exportheader.md

@@ -25,7 +25,7 @@ The argument to `/exportHeader` is a `/headerName` command-line option that spec
 
 **`/exportHeader`** is available starting in Visual Studio 2019 version 16.10 Preview 2.
 
-The **`/exportHeader`** compiler option requires you enable the [/std:c++latest](std-specify-language-standard-version.md) option. 
+The **`/exportHeader`** compiler option requires you enable the [`/std:c++latest`](std-specify-language-standard-version.md) option.
 
 One **`/exportHeader`** compiler option can specify as many header-name arguments as your build requires. You don't need to specify them separately.
 

docs/build/reference/sourcedependencies-directives.md

@@ -101,4 +101,4 @@ You normally shouldn't set this yourself in the Visual Studio development enviro
 ## See also
 
 [MSVC compiler options](compiler-options.md)\
-[MSVC compiler command-line syntax](compiler-command-line-syntax.md)
+[MSVC compiler command-line syntax](compiler-command-line-syntax.md)

docs/build/reference/translateinclude.md

@@ -69,7 +69,6 @@ To enable `/translateInclude`, set the **Translate Includes to Imports** option
 1. Change the **Translate Includes to Imports** dropdown to **Yes**
 ![Screenshot of the Property Pages dialog with the Translate Includes to Imports property highlighted.](../media/vs2019-translate-includes-option.png)
 
-
 ## See also
 
 [`/headerUnit` (Use header unit IFC)](headerunit.md).\

docs/build/reference/vmm-vms-vmv-general-purpose-representation.md

@@ -54,7 +54,6 @@ When you specify one of these inheritance-model options, that model gets used fo
 
 1. Enter the compiler option in the **Additional Options** box.
 
-
 ### To set this compiler option programmatically
 
 - See <xref:Microsoft.VisualStudio.VCProjectEngine.VCCLCompilerTool.AdditionalOptions%2A>.

docs/build/walkthrough-compiling-a-native-cpp-program-on-the-command-line.md

@@ -98,7 +98,7 @@ Before you can build a C or C++ program on the command line, verify that the too
    ```
 
    The dates and other details will differ on your computer.
-   
+
    > [!NOTE]
    > If you don't see your source code file, *`hello.cpp`*, make sure the current working directory in your command prompt is the *`C:\hello`* directory you created. Also make sure that this is the directory where you saved your source file. And make sure that you saved the source code with a *`.cpp`* file name extension, not a *`.txt`* extension. Your source file gets saved in the current directory as a *`.cpp`* file automatically if you open Notepad at the command prompt by using the **`notepad hello.cpp`** command. Notepad's behavior is different if you open it another way: By default, Notepad appends a *`.txt`* extension to new files when you save them. It also defaults to saving files in your *Documents* directory. To save your file with a *`.cpp`* extension in Notepad, choose **File** > **Save As**. In the **Save As** dialog, navigate to your *`C:\hello`* folder in the directory tree view control. Then use the **Save as type** dropdown control to select **All Files (\*.\*)**. Enter *`hello.cpp`* in the **File name** edit control, and then choose **Save** to save the file.
 

docs/build/walkthrough-header-units.md

@@ -50,6 +50,7 @@ In this example, you'll compile a header file as a header unit. Start by creatin
 
 1. Create a new C++ console app project.
 1. Replace the source file content as follows:
+
     ```cpp
     #include "Pythagorean.h"
 
@@ -59,7 +60,9 @@ In this example, you'll compile a header file as a header unit. Start by creatin
         return 0;
     }
     ```
+
 1. Add a header file called `Pythagorean.h`, and replace its content with this code:
+
     ```cpp
     #ifndef PYTHAGOREAN
     #define PYTHAGOREAN
@@ -110,4 +113,4 @@ If you want to convert only a few header files to header units, this approach is
 [Overview of modules in C++](../cpp/modules-cpp.md) \
 [`/translateInclude`](./reference/translateinclude.md) \
 [`/exportHeader`](./reference/module-exportheader.md) \
-[`/headerUnit`](./reference/headerunit.md)
+[`/headerUnit`](./reference/headerunit.md)

docs/build/walkthrough-import-stl-header-units.md

@@ -63,6 +63,7 @@ This step creates a project that includes two libraries: `<iostream>` and `<vect
 
 1. With Visual Studio, create a new C++ console app project.
 1. Modify the source file as follows:
+
     ```cpp
     import <iostream>;
     import <vector>;
@@ -73,7 +74,7 @@ This step creates a project that includes two libraries: `<iostream>` and `<vect
         std::cout << numbers[1];
     }
     ```
-    
+
 ### Set project options and run the project
 
 Follow these steps to set the options that cause the build system to scan for imported headers that can be compiled into header units.
@@ -103,7 +104,7 @@ The more flexible way to consume STL headers is to create one or more static lib
 
 This option ensures that header units for a particular header will be built only once. It's similar to using a shared precompiled header file, but it's much easier.
 
-In this example, you'll create a project that imports `<iostream>` and `<vector>`. After the solution is built, you'll reference this shared header unit project from another C++ project. Everywhere `import <iostream>;` or `import <vector>;` is found in the referencing project, the project will import the built header unit for that library instead of running the contents of the library header through the preprocessor. 
+In this example, you'll create a project that imports `<iostream>` and `<vector>`. After the solution is built, you'll reference this shared header unit project from another C++ project. Everywhere `import <iostream>;` or `import <vector>;` is found in the referencing project, the project will import the built header unit for that library instead of running the contents of the library header through the preprocessor.
 
 In projects that include the same library header in multiple files, this change will improve build performance similarly to how PCH files do. The header won't have to be processed over and over by the files that include it. Instead, the already processed compiled header unit will be imported.
 
@@ -157,6 +158,7 @@ Next, create a project that will use the built `<vector>` and `<iostream>` share
     ```
 
 Change the **C++ Language Standard** for the compiler. To use header units, you need the [`/std:c++latest`](./reference/std-specify-language-standard-version.md) switch.
+
 1. In **Solution Explorer**, right-click the **Walkthrough** project and select **Properties**. The project property pages open:
 :::image type="content" source="media/set-cpp-language-latest.png" alt-text="Screenshot that shows setting the language standard to the preview version.":::
 1. In the left pane of the **Walkthrough** project property pages, select **Configuration Properties** > **General**.
@@ -165,7 +167,7 @@ Change the **C++ Language Standard** for the compiler. To use header units, you
 
 In the **Walkthrough** project, add a reference to the **SharedPrj** project.
 
-1. In the **Walkthrough** project, select the **References** node, and then select **Add Reference**. Select **SharedPrj** in the list of projects: 
+1. In the **Walkthrough** project, select the **References** node, and then select **Add Reference**. Select **SharedPrj** in the list of projects:
 :::image type="content" source="./media/add-reference-to-walkthrough.png" alt-text="Screenshot that shows the Add Reference dialog. It's used to add a reference to the Walkthrough project.":::
 Now that you've added this reference, the build system will use the header units built by **SharedPrj** whenever an `import` in the **Walkthrough** project matches one of the built header units in **SharedPrj**.
 1. Select **OK** to close the **Add Reference** dialog.
@@ -192,6 +194,7 @@ For example, if you have `#include <vector>` in your project and you reference a
 ## Reuse header units among projects
 
 Header units built by a static library project are automatically available to all directly and indirectly referencing projects. There are project settings that allow you to select which header units should be automatically available to all referencing projects. The settings are in project settings under **VC++ Directories**.
+
 1. In **Solution Explorer**, right-click the project and select **Properties**.
 1. In the left pane of the project properties page, select **VC++ Directories**:
 :::image type="content" source="media/public-include-module-directories-setting.png" alt-text="Screenshot that shows public project content properties, like Public Include Directories and All Header Files are Public.":::
@@ -209,18 +212,20 @@ Typically, the easiest way to reuse header units among solutions is to reference
 But if you need to use a built header unit that you don't have the project for, you can specify where the built *`.ifc`* file is so you can import it in your solution.
 
 To access this setting:
+
 1. On the main menu, select **Project** > **Properties**. The project properties page opens.
 1. In the left pane of the project properties page, select **C/C++** > **General**.
 1. In the **Additional Module Dependencies** list, add the modules to reference. Here's an example of the format to use for **Additional Module Dependencies**: `ModuleName1=Path\To\ModuleName1.ifc; ModuleName2=Path\To\ModuleName2.ifc`
 :::image type="content" source="media/vs2019-additional-module-dependencies.png" alt-text="Screenshot showing project properties under C/C++, General, which Additional Module Dependencies selected.":::
 
 ## Select among multiple copies of a header unit
- 
+
 If you reference two or more projects that built two or more header units with the same name, or that built two or more header units for the same header file, there will be multiple header units to choose from for the same import. You might have different versions of the header unit that were built with different compiler settings, for example, and need to inform the compiler which one to use.
 
 Use  the project properties **C/C++** > **Additional Header Unit Dependencies** setting to resolve collisions by specifying which header unit should be used. Otherwise, you can't predict which one will be picked.
 
 To access this setting:
+
 1. On the main menu, select **Project** > **Properties**. The project properties page opens.
 1. In the left pane of the project properties page, select **C/C++** > **General**.
 1. Use **Additional Header Unit Dependencies** to resolve collisions by specifying which module or header unit should be used for the project. Use this format for **Additional Header Unit Dependencies**: `Path\To\Header1.h= Path\To\HeaderUnit1.ifc;Path\To\Header2.h= Path\To\ HeaderUnit2.ifc`

docs/c-language/alignment-c.md

@@ -131,4 +131,4 @@ Windows SDK 10.0.20348.0 (version 2104) or later. See [Windows 10 SDK](https://d
 
 [`/std` (Specify Language Standard Version)](../build/reference/std-specify-language-standard-version.md)\
 [C++ `alignof` and `alignas`](../cpp/alignment-cpp-declarations.md#alignof-and-alignas)\
-[Compiler handling of data alignment](../cpp/alignment-cpp-declarations.md#compiler-handling-of-data-alignment)
+[Compiler handling of data alignment](../cpp/alignment-cpp-declarations.md#compiler-handling-of-data-alignment)

docs/c-language/expanding-wildcard-arguments.md

@@ -10,7 +10,7 @@ Wildcard argument expansion is Microsoft-specific.
 
 When you run a C program, you can use either of the two wildcards, the question mark (**`?`**) and the asterisk (**`*`**), to specify filename and path arguments on the command line.
 
-By default, wildcards aren't expanded in command-line arguments. You can replace the normal argument vector `argv` loading routine with a version that does expand wildcards by linking with the *`setargv.obj`* or *`wsetargv.obj`* file. If your program uses a `main` function, link with *`setargv.obj`*. If your program uses a `wmain` function, link with *`wsetargv.obj`*. Both of these have equivalent behavior. 
+By default, wildcards aren't expanded in command-line arguments. You can replace the normal argument vector `argv` loading routine with a version that does expand wildcards by linking with the *`setargv.obj`* or *`wsetargv.obj`* file. If your program uses a `main` function, link with *`setargv.obj`*. If your program uses a `wmain` function, link with *`wsetargv.obj`*. Both of these have equivalent behavior.
 
 To link with *`setargv.obj`* or *`wsetargv.obj`*, use the **`/link`** option. For example:
 

docs/c-language/generic-selection.md

@@ -79,4 +79,4 @@ Windows SDK 10.0.20348.0 (version 2104) or later. See [Windows 10 SDK](https://d
 ## See also
 
 [`/std` (Specify language standard version)](../build/reference/std-specify-language-standard-version.md)\
-[Type-generic math](../c-runtime-library/tgmath.md)
+[Type-generic math](../c-runtime-library/tgmath.md)

docs/c-language/noreturn.md

@@ -16,7 +16,7 @@ The primary benefits for using `_Noreturn` (or the equivalent `noreturn`) are ma
 
 A function marked `noreturn` shouldn't include a return type because it doesn't return a value to the caller. It should be `void`.
 
-## Example using `noreturn` macro and `_Noreturn `keyword
+## Example using `noreturn` macro and `_Noreturn` keyword
 
 The following example demonstrates the `_Noreturn` keyword and the equivalent `noreturn` macro.
 

docs/c-language/type-qualifiers.md

@@ -53,7 +53,7 @@ If the specification of an array type includes type qualifiers, the element is q
 If **`volatile`** is used alone, **`int`** is assumed. The **`volatile`** type specifier can be used to provide reliable access to special memory locations. Use **`volatile`** with data objects that may be accessed or altered by signal handlers, by concurrently executing programs, or by special hardware such as memory-mapped I/O control registers. You can declare a variable as **`volatile`** for its lifetime, or you can cast a single reference to be **`volatile`**.
 
 - An item can be both **`const`** and **`volatile`**, in which case the item couldn't be legitimately modified by its own program, but could be modified by some asynchronous process.
- 
+
 ## `restrict`
 
 The **`restrict`** type qualifier, introduced in C99 and available in [`/std:c11` or `/std:c17`](../build/reference/std-specify-language-standard-version.md) mode, can be applied to pointer declarations. It qualifies the pointer, not what it points at.

docs/c-runtime-library/country-region-strings.md

@@ -6,7 +6,7 @@ helpviewer_keywords: ["country/region strings"]
 ---
 # Country/Region Strings
 
-Country and region strings can be combined with a language string to create a locale specification for the `setlocale`, `_wsetlocale`, `_create_locale`, and `_wcreate_locale` functions. 
+Country and region strings can be combined with a language string to create a locale specification for the `setlocale`, `_wsetlocale`, `_create_locale`, and `_wcreate_locale` functions.
 
 For lists of country and region names that are supported by various Windows operating system versions, see the **Language**, **Location**, and **Language tag** columns of the table in [Appendix A: Product Behavior](/openspecs/windows_protocols/ms-lcid/a9eac961-e77d-41a6-90a5-ce1a8b0cdb9c) in \[MS-LCID]: Windows Language Code Identifier (LCID) Reference. For an example of code that enumerates available locale names and related values, see [NLS: Name-based APIs Sample](/windows/win32/intl/nls--name-based-apis-sample).
 

docs/c-runtime-library/crt-library-features.md

@@ -102,5 +102,5 @@ Be careful if your program passes certain CRT resources across DLL boundaries. R
 
 ## See also
 
-- [C runtime library reference](../c-runtime-library/c-run-time-library-reference.md)
-- [Redistributing Visual C++ Files](../windows/redistributing-visual-cpp-files.md)
+[C runtime library reference](../c-runtime-library/c-run-time-library-reference.md)\
+[Redistributing Visual C++ Files](../windows/redistributing-visual-cpp-files.md)