Edit pass on System.CommandLine (#47693)

Author: gewarren

docs/standard/commandline/design-guidance.md

@@ -11,9 +11,9 @@ ms.topic: conceptual
 
 # Design guidance
 
-The following sections present guidance that we recommend you follow when designing a CLI. Think of what your app expects on the command line as similar to what a REST API server expects in the URL. Consistent rules for REST APIs are what make them readily usable to client app developers. In the same way, users of your command-line apps will have a better experience if the CLI design follows common patterns.
+The following sections present guidance for designing a CLI. Think of what your app expects on the command line as similar to what a REST API server expects in the URL. Consistent rules for REST APIs are what make them readily usable to client app developers. In the same way, users of your command-line apps will have a better experience if the CLI design follows common patterns.
 
-Once you create a CLI, it is hard to change, especially if your users have used your CLI in scripts they expect to keep running. The guidelines here were developed after the .NET CLI, and it doesn't always follow these guidelines. We are updating the .NET CLI where we can do so without introducing breaking changes. An example of this work is the new design for `dotnet new` in .NET 7.
+Once you create a CLI, it is hard to change it, especially if your users have used your CLI in scripts they expect to keep running.
 
 ## Symbols
 
@@ -39,7 +39,7 @@ In particular, avoid using any of the following aliases differently than their c
 
 * `-i` for `--interactive`.
 
-  This option signals to the user that they may be prompted for inputs to questions that the command needs answered. For example, prompting for a username. Your CLI may be used in scripts, so use caution in prompting users who have not specified this switch.
+  This option signals to the user that they might be prompted for inputs to questions that the command needs answered. For example, prompting for a username. Your CLI might be used in scripts, so use caution in prompting users who haven't specified this switch.
 
 * `-o` for `--output`.
 

docs/standard/commandline/get-started-tutorial.md

@@ -11,7 +11,7 @@ helpviewer_keywords:
 ---
 # Tutorial: Get started with System.CommandLine
 
-[!INCLUDE [scl-preview](../../../includes/scl-preview.md)]
+[!INCLUDE [scl-preview](./includes/preview.md)]
 
 This tutorial shows how to create a .NET command-line app that uses the [`System.CommandLine` library](index.md). You'll begin by creating a simple root command that has one option. Then you'll build on that base, creating a more complex app that contains multiple subcommands and different options for each command.
 
@@ -166,7 +166,7 @@ Options:
   --file          The file to read and display on the conso
 ```
 
-`System.CommandLine.RootCommand` by default provides [Help option](how-to-customize-help.md#customize-help-output), [Version option](syntax.md#version-option) and [Suggest directive](syntax.md#suggest-directive). `ParseResult.Invoke` method is responsible for invoking the action of parsed symbol. It could be the action explicitly defined for our command, or the help action defined by `System.CommandLine` for `System.CommandLine.Help.HelpOption`. Moreover, when it detects any parse errors, it prints them to the standard error, prints help to standard output and returns `1` exit code:
+<xref:System.CommandLine.RootCommand> by default provides [Help option](how-to-customize-help.md#customize-help-output), [Version option](syntax.md#version-option), and [Suggest directive](syntax.md#suggest-directive). The <xref:System.CommandLine.ParseResult.Invoke?displayProperty=nameWithType> method is responsible for invoking the action of parsed symbol. It could be the action explicitly defined for the command, or the help action defined by `System.CommandLine` for `System.CommandLine.Help.HelpOption`. Moreover, when it detects any parse errors, it prints them to the standard error, prints help to standard output, and returns `1` as the exit code:
 
 ```console
 scl --invalid bla

docs/standard/commandline/how-to-configure-the-parser.md

@@ -12,21 +12,21 @@ ms.topic: how-to
 
 # How to configure the parser in System.CommandLine
 
-[!INCLUDE [scl-preview](../../../includes/scl-preview.md)]
+[!INCLUDE [scl-preview](./includes/preview.md)]
 
-`System.CommandLine.CommandLineConfiguration` is a class that provides properties to configure the parser. It is an optional argument for every `Parse` method, such as `System.CommandLine.Command.Parse` or `System.CommandLine.Parsing.CommandLineParser.Parse`. When it is not provided, the default configuration is used.
+<xref:System.CommandLine.CommandLineConfiguration> is a class that provides properties to configure the parser. It is an optional argument for every `Parse` method, such as <xref:System.CommandLine.Command.Parse*?displayProperty=nameWithType> and <xref:System.CommandLine.Parsing.CommandLineParser.Parse*?displayProperty=nameWithType>. When it isn't provided, the default configuration is used.
 
-Every `System.CommandLine.ParseResult` instance has a `System.CommandLine.ParseResult.Configuration` property that returns the configuration used for parsing.
+<xref:System.CommandLine.ParseResult> has a <xref:System.CommandLine.ParseResult.Configuration> property that returns the configuration used for parsing.
 
 ## Standard output and error
 
-`System.CommandLine.CommandLineConfiguration` makes testing, as well as many extensibility scenarios, easier than using `System.Console`. It exposes two `TextWriter` properties: `Output` and `Error`. These can be set to any `TextWriter` instance, such as a `StringWriter`, which can be used to capture output for testing.
+`CommandLineConfiguration` makes testing, as well as many extensibility scenarios, easier than using `System.Console`. It exposes two `TextWriter` properties: `Output` and `Error`. These can be set to any `TextWriter` instance, such as a `StringWriter`, which can be used to capture output for testing.
 
-Let's define a simple command that writes to standard output:
+Define a simple command that writes to standard output:
 
 :::code language="csharp" source="snippets/configuration/csharp/Program.cs" id="rootcommand":::
 
-Now, let's use `CommandLineConfiguration` to capture the output:
+Now, use `CommandLineConfiguration` to capture the output:
 
 :::code language="csharp" source="snippets/configuration/csharp/Program.cs" id="captureoutput":::
 

docs/standard/commandline/how-to-customize-help.md

@@ -12,7 +12,7 @@ ms.topic: how-to
 
 # Customize help output
 
-Command-line apps typically provide an option to display a brief description of the available commands, options, and arguments. `System.CommandLine` provides `System.CommandLine.Help.HelpOption` that is by default included in the [RootCommand](syntax.md#root-command) options. System.CommandLine.Help.HelpOption generates help output for defined symbols by using the information exposed by `System.CommandLine.Symbol.Name`, `System.CommandLine.Symbol.HelpName`, `System.CommandLine.Symbol.Description`, and other properties like default value or completion sources.
+Command-line apps typically provide an option to display a brief description of the available commands, options, and arguments. `System.CommandLine` provides <xref:System.CommandLine.Help.HelpOption>, which is included in the [RootCommand](syntax.md#root-command) options by default. `HelpOption` generates help output for defined symbols by using the information exposed by <xref:System.CommandLine.Symbol.Name>, <xref:System.CommandLine.Option.HelpName>, <xref:System.CommandLine.Symbol.Description>, and other properties like default value or completion sources.
 
 :::code language="csharp" source="snippets/customize-help/csharp/Program.cs" id="original" :::
 
@@ -45,11 +45,11 @@ dotnet -?
 dotnet /?
 ```
 
-Help output doesn't necessarily show all available commands, arguments, and options. Some of them might be *hidden* via the `System.CommandLine.Symbol.Hidden` property, which means they don't show up in help output (and completions) but can be specified on the command line.
+Help output doesn't necessarily show all available commands, arguments, and options. Some of them might be *hidden* via the <xref:System.CommandLine.Symbol.Hidden> property, which means they don't show up in help output (and completions) but can be specified on the command line.
 
 ## Help customization
 
- You can customize help output for commands by defining specific help text for each symbol, providing further clarity to users regarding their usage.
+You can customize help output for commands by defining specific help text for each symbol, providing further clarity to users regarding their usage.
 
 To customize the name of an option's argument, use the option's `System.CommandLine.Option.HelpName` property.
 

docs/standard/commandline/how-to-customize-parsing-and-validation.md

@@ -12,7 +12,7 @@ ms.topic: how-to
 
 # How to customize parsing and validation in System.CommandLine
 
-[!INCLUDE [scl-preview](../../../includes/scl-preview.md)]
+[!INCLUDE [scl-preview](./includes/preview.md)]
 
 By default, System.CommandLine provides a set of built-in parsers that can parse many common types:
 
@@ -36,21 +36,21 @@ Other types are not supported, but you can create custom parsers for them. You c
 
 Every option, argument, and command can have one or more validators. Validators are used to ensure that the parsed value meets certain criteria. For example, you can validate that a number is positive, or that a string is not empty. You can also create complex validators that check against multiple conditions.
 
-Every symbol type in System.CommandLine has a `Validators` property that contains a list of validators. The validators are executed after the input is parsed, and they can report an error if the validation fails.
+Every symbol type in System.CommandLine has a <xref:System.CommandLine.Option.Validators> property that contains a list of validators. The validators are executed after the input is parsed, and they can report an error if the validation fails.
 
 To provide custom validation code, call `System.CommandLine.Option.Validators.Add` on your option or argument (or command), as shown in the following example:
 
 :::code language="csharp" source="snippets/model-binding/csharp/AddValidator.cs" id="delayOption" :::
 
 System.CommandLine provides a set of built-in validators that can be used to validate common types:
 
-- `AcceptExistingOnly` - configures given option or argument to accept only values corresponding to an existing file or directory.
-- `AcceptLegalFileNamesOnly` - configures given option or argument to accept only values representing legal file names.
-- `AcceptOnlyFromAmong` - configures given option or argument to accept only values from a specified set of values.
+* `AcceptExistingOnly` - configures given option or argument to accept only values corresponding to an existing file or directory.
+* `AcceptLegalFileNamesOnly` - configures given option or argument to accept only values representing legal file names.
+* `AcceptOnlyFromAmong` - configures given option or argument to accept only values from a specified set of values.
 
 ## Custom parsers
 
-Custom parsers are required to parse types with no default parser, such as complex types. They can also be used to parse supported types in a different way than the built-in parsers.
+To parse types with no default parser, such as complex types, you need a custom parser. Custom parsers can also be used to parse supported types in a different way than the built-in parsers.
 
 Suppose you have a `Person` type:
 
@@ -75,5 +75,5 @@ Here are some examples of what you can do with `CustomParser` that you can't do
 
 ## See also
 
-- [How to parse and invoke the result](how-to-parse-and-invoke.md)
-- [System.CommandLine overview](index.md)
+* [How to parse and invoke the result](how-to-parse-and-invoke.md)
+* [System.CommandLine overview](index.md)

docs/standard/commandline/how-to-enable-tab-completion.md

@@ -12,9 +12,9 @@ ms.topic: how-to
 
 # Tab completion for System.CommandLine
 
-[!INCLUDE [scl-preview](../../../includes/scl-preview.md)]
+[!INCLUDE [scl-preview](./includes/preview.md)]
 
-Apps that use `System.CommandLine` have built-in support for tab completion in certain shells. To enable it, the end user must take a few steps once per shell. Once this is done, tab completion is automatic for static values in your app, such as enum values or values defined by calling `System.CommandLine.Option<T>.AcceptOnlyFromAmong`. You can also customize tab completion by providing values dynamically at runtime.
+Apps that use `System.CommandLine` have built-in support for tab completion in certain shells. To enable it, the end user must take a few steps once per shell. Once this is done, tab completion is automatic for static values in your app, such as enum values or values defined by calling <xref:System.CommandLine.Option`1.AcceptOnlyFromAmong(System.String[])>. You can also customize tab completion by providing values dynamically at runtime.
 
 ## Enable tab completion
 
@@ -59,7 +59,7 @@ The values shown when the Tab key is pressed are provided as `CompletionItem` in
 The following `CompletionItem` properties are set:
 
 * `Label` is the completion value to be shown.
-* `SortText` ensures that the values in the list are presented in the correct order. It is set by converting `i` to a two-digit string, so that sorting is based on 01, 02, 03, and so on, through 14. If you do not set this parameter, sorting is based on the `Label`, which in this example is in short date format and will not sort correctly.
+* `SortText` ensures that the values in the list are presented in the correct order. It is set by converting `i` to a two-digit string, so that sorting is based on 01, 02, 03, and so on, through 14. If you don't set this parameter, sorting is based on the `Label`, which in this example is in short date format and will not sort correctly.
 
 There are other `CompletionItem` properties, such as `Documentation` and `Detail`, but they are not yet used in `System.CommandLine`.