Fixes GitHub issue #30860 - Confusing use of "default" for langversion (#37802)

* edits

* fix

* edits

* fix

* Update docs/csharp/language-reference/compiler-options/language.md

---------

Co-authored-by: Bill Wagner <[email protected]>

Author: v-thepet

docs/csharp/language-reference/compiler-options/language.md

@@ -1,7 +1,7 @@
 ---
 description: "C# Compiler Options for language feature rules. These options control how the compiler interprets certain language constructs."
 title: "C# Compiler Options - language feature rules"
-ms.date: 07/06/2021
+ms.date: 10/30/2023
 f1_keywords:
   - "cs.build.options"
 helpviewer_keywords:
@@ -60,7 +60,9 @@ This option specifies the names of one or more symbols that you want to define.
 
 ## LangVersion
 
-Causes the compiler to accept only syntax that is included in the chosen C# language specification.
+The default language version for the C# compiler depends on the target framework for your application and the version of the SDK or Visual Studio installed. Those rules are defined in [C# language versioning](../configure-language-version.md#defaults).
+
+The **LangVersion** option causes the compiler to accept only syntax that is included in the specified C# language specification, for example:
 
 ```xml
 <LangVersion>9.0</LangVersion>
@@ -70,18 +72,22 @@ The following values are valid:
 
 [!INCLUDE [lang-versions-table](../includes/langversion-table.md)]
 
-The default language version depends on the target framework for your application and the version of the SDK or Visual Studio installed. Those rules are defined in [C# language versioning](../configure-language-version.md#defaults).
-
 > [!IMPORTANT]
-> The `latest` value is generally not recommended. With it, the compiler enables the latest features, even if those features depend on updates not included in the configured target framework. Without this setting, your project uses the compiler version recommended for your target framework. You can update the target framework to access newer language features.
+> The `latest` value is generally not recommended. With `latest`, the compiler enables the latest features, even if those features depend on updates not included in the configured target framework.
+
+### Considerations
+
+- To ensure that your project uses the default compiler version recommended for your target framework, don't use the **LangVersion** option. You can update the target framework to access newer language features.
+
+- Specifying **LangVersion** with the `default` value is different from omitting the **LangVersion** option. Specifying `default` uses the latest version of the language that the compiler supports, without taking into account the target framework. For example, building a project that targets .NET 6 from Visual Studio version 17.6 uses C# 10 if **LangVersion** isn't specified, but uses C# 11 if **LangVersion** is set to `default`.
 
-Metadata referenced by your C# application isn't subject to the **LangVersion** compiler option.
+- Metadata referenced by your C# application isn't subject to the **LangVersion** compiler option.
 
-Because each version of the C# compiler contains extensions to the language specification, **LangVersion** doesn't give you the equivalent functionality of an earlier version of the compiler.
+- Because each version of the C# compiler contains extensions to the language specification, **LangVersion** doesn't give you the equivalent functionality of an earlier version of the compiler.
 
-Additionally, while C# version updates generally coincide with major .NET releases, the new syntax and features aren't necessarily tied to that specific framework version. Each specific feature has its own minimum .NET API or common language runtime requirements that may allow it to run on downlevel frameworks by including NuGet packages or other libraries.
+- While C# version updates generally coincide with major .NET releases, the new syntax and features aren't necessarily tied to that specific framework version. Each specific feature has its own minimum .NET API or common language runtime requirements that may allow it to run on downlevel frameworks by including NuGet packages or other libraries.
 
-Regardless of which **LangVersion** setting you use, use the current version of the common language runtime to create your .exe or .dll. One exception is friend assemblies and [**ModuleAssemblyName**](advanced.md#moduleassemblyname), which work under **-langversion:ISO-1**.
+- Regardless of which **LangVersion** setting you use, use the current version of the common language runtime to create your *.exe* or *.dll*. One exception is friend assemblies and [ModuleAssemblyName](advanced.md#moduleassemblyname), which work under **-langversion:ISO-1**.
 
 For other ways to specify the C# language version, see [C# language versioning](../configure-language-version.md).
 

docs/csharp/language-reference/configure-language-version.md

@@ -2,7 +2,7 @@
 title: C# language versioning - C# Guide
 description: Learn about how the C# language version is determined based on your project and the reasons behind that choice. Learn how to override the default manually.
 ms.custom: "updateeachrelease"
-ms.date: 02/25/2022
+ms.date: 10/30/2023
 ---
 
 # C# language versioning
@@ -19,18 +19,18 @@ The compiler determines a default based on these rules:
 
 [!INCLUDE [langversion-table](includes/default-langversion-table.md)]
 
-When your project targets a preview framework that has a corresponding preview language version, the language version used is the preview language version. You use the latest features with that preview in any environment, without affecting projects that target a released .NET Core version.
+If your project targets a `preview` framework that has a corresponding preview language version, the language version used is the preview language version. You use the latest features with that preview in any environment, without affecting projects that target a released .NET Core version.
 
 > [!IMPORTANT]
-> The new project template for Visual Studio 2017 added a `<LangVersion>latest</LangVersion>` entry to new project files. If you upgrade the target framework for these projects, they [override the default behavior](#override-a-default). You should remove the `<LangVersion>latest</LangVersion>` from your project file when you update the .NET SDK. Then, your project will use the compiler version recommended for your target framework. You can update the target framework to access newer language features.
+> The new project template for Visual Studio 2017 added a `<LangVersion>latest</LangVersion>` entry to new project files. If you upgrade the target framework for these projects, the `<LangVersion>` setting can [override the default](#override-the-default) for the new target framework. Be sure to remove the `<LangVersion>latest</LangVersion>` from your project file to ensure your project uses the recommended compiler version for your target framework. You can update the target framework to access newer language features.
 
-## Override a default
+## Override the default
 
 If you must specify your C# version explicitly, you can do so in several ways:
 
 - Manually edit your [project file](#edit-the-project-file).
 - Set the language version [for multiple projects in a subdirectory](#configure-multiple-projects).
-- Configure the [**LangVersion** compiler option](compiler-options/language.md#langversion).
+- Configure the [LangVersion compiler option](compiler-options/language.md#langversion).
 
 > [!TIP]
 > You can see the language version in Visual Studio in the project properties page. Under the *Build* tab, the *Advanced* pane displays the version selected.
@@ -51,7 +51,7 @@ The value `preview` uses the latest available preview C# language version that y
 
 ### Configure multiple projects
 
-To configure multiple projects, you can create a **Directory.Build.props** file that contains the `<LangVersion>` element. You typically do that in your solution directory. Add the following to a **Directory.Build.props** file in your solution directory:
+To configure multiple projects, you can create a *Directory.Build.props* file, typically in your solution directory, that contains the `<LangVersion>` element. Add the following setting to the *Directory.Build.props* file:
 
 ```xml
 <Project>
@@ -61,10 +61,13 @@ To configure multiple projects, you can create a **Directory.Build.props** file
 </Project>
 ```
 
-Builds in all subdirectories of the directory containing that file will use the preview C# version. For more information, see [Customize your build](/visualstudio/msbuild/customize-your-build).
+Builds in all subdirectories of the directory containing that file now use the preview C# version. For more information, see [Customize your build](/visualstudio/msbuild/customize-your-build).
 
 ## C# language version reference
 
-The following table shows all current C# language versions. Your compiler may not necessarily understand every value if it's older. If you install the latest .NET SDK, then you have access to everything listed.
+The following table shows all current C# language versions. Older compilers might not understand every value. If you install the latest .NET SDK, you have access to everything listed.
 
 [!INCLUDE [langversion-table](includes/langversion-table.md)]
+
+>[!NOTE]
+>Specifying **LangVersion** with the `default` value is different from omitting the **LangVersion** option. Specifying `default` uses the latest version of the language that the compiler supports, without taking into account the target framework. For example, building a project that targets .NET 6 from the current version of Visual Studio 2022 uses C# 10 if **LangVersion** isn't specified, but uses C# 11 if **LangVersion** is set to `default`.