diff --git a/src/System.CommandLine/Argument.cs b/src/System.CommandLine/Argument.cs
index f1c915045e..af2937f055 100644
--- a/src/System.CommandLine/Argument.cs
+++ b/src/System.CommandLine/Argument.cs
@@ -10,7 +10,7 @@
namespace System.CommandLine
{
///
- /// A symbol defining a value that can be passed on the command line to a command or option .
+ /// Represents a symbol that defines a value that can be passed on the command line to a command or option .
///
public abstract class Argument : Symbol
{
@@ -22,7 +22,7 @@ public abstract class Argument : Symbol
///
/// Initializes a new instance of the Argument class.
///
- /// The name of the argument. This can be used to look up the parsed value and is displayed in help
+ /// The name of the argument. This value can be used to look up the parsed value and is displayed in help if is null.
protected Argument(string name) : base(name, allowWhitespace: true)
{
}
@@ -48,8 +48,11 @@ public ArgumentArity Arity
/// Gets or sets the placeholder name shown in usage help for the argument's value.
/// The value will be wrapped in angle brackets (< and > ).
///
+ ///
+ /// The name to show as the placeholder for the argument's value.
+ ///
///
- /// If null , the of the argument will be used.
+ /// If null , the of the argument is used.
///
///
/// An argument with of argument and a
@@ -57,9 +60,6 @@ public ArgumentArity Arity
/// <Value> . If is not set,
/// help output will show: <argument> .
///
- ///
- /// The name to show as the placeholder for the argument's value.
- ///
public string? HelpName { get; set; }
internal TryConvertArgument? ConvertArguments
@@ -107,12 +107,12 @@ public List>> CompletionSour
}
///
- /// Gets or sets the that the argument's parsed tokens will be converted to.
+ /// Gets the type that the argument's parsed tokens will be converted to.
///
public abstract Type ValueType { get; }
///
- /// Provides a list of argument validators. Validators can be used
+ /// Gets a list of argument validators. Validators can be used
/// to provide custom errors based on user input.
///
public List> Validators => _validators ??= new ();
@@ -122,7 +122,7 @@ public List>> CompletionSour
///
/// Gets the default value for the argument.
///
- /// Returns the default value for the argument, if defined. Null otherwise.
+ /// The default value for the argument, if defined; otherwise, .
public object? GetDefaultValue()
{
var command = Parents.FlattenBreadthFirst(x => x.Parents)
@@ -135,7 +135,7 @@ public List>> CompletionSour
internal abstract object? GetDefaultValue(ArgumentResult argumentResult);
///
- /// Specifies if a default value is defined for the argument.
+ /// Gets a value that indicates if a default value is defined for the argument.
///
public abstract bool HasDefaultValue { get; }
diff --git a/src/System.CommandLine/Argument{T}.cs b/src/System.CommandLine/Argument{T}.cs
index 2a9dd55592..999ac5604f 100644
--- a/src/System.CommandLine/Argument{T}.cs
+++ b/src/System.CommandLine/Argument{T}.cs
@@ -15,17 +15,17 @@ public class Argument : Argument
///
/// Initializes a new instance of the Argument class.
///
- /// The name of the argument. This can be used to look up the parsed value and is displayed in help
+ /// The name of the argument. This name can be used to look up the parsed value and is displayed in help.
public Argument(string name) : base(name)
{
}
///
- /// The delegate to invoke to create the default value.
+ /// Gets or sets the delegate to invoke to create the default value.
///
///
- /// It's invoked when there was no parse input provided for given Argument.
- /// The same instance can be set as , in such case
+ /// This delegate is invoked when there was no parse input provided for given Argument.
+ /// The same instance can be set as . In that case,
/// the delegate is also invoked when an input was provided.
///
public Func? DefaultValueFactory
@@ -45,11 +45,11 @@ public Func? DefaultValueFactory
}
///
- /// A custom argument parser.
+ /// Gets or sets a custom argument parser.
///
///
- /// It's invoked when there was parse input provided for given Argument.
- /// The same instance can be set as , in such case
+ /// The custom parser is invoked when there was parse input provided for a given Argument.
+ /// The same instance can be set as ; in that case,
/// the delegate is also invoked when no input was provided.
///
public Func? CustomParser
diff --git a/src/System.CommandLine/Command.cs b/src/System.CommandLine/Command.cs
index be565651d2..a44f9789e0 100644
--- a/src/System.CommandLine/Command.cs
+++ b/src/System.CommandLine/Command.cs
@@ -18,9 +18,9 @@ namespace System.CommandLine
/// Represents a specific action that the application performs.
///
///
- /// Use the Command object for actions that correspond to a specific string (the command name). See
- /// for simple applications that only have one action. For example, dotnet run
- /// uses run as the command.
+ /// Use the Command object for actions that correspond to a specific string (the command name).
+ /// For simple applications that only have one action, see .
+ /// For example, dotnet run uses run as the command.
///
public class Command : Symbol, IEnumerable
{
@@ -57,28 +57,31 @@ public IEnumerable Children
}
///
- /// Represents all of the arguments for the command.
+ /// Gets all of the arguments for the command.
///
public IList Arguments => _arguments ??= new(this);
internal bool HasArguments => _arguments?.Count > 0 ;
///
- /// Represents all of the options for the command, inherited options that have been applied to any of the command's ancestors.
+ /// Gets all of the options for the command.
///
+ ///
+ /// This collection doesn't include options on parent commands where Option.Recursive is . Those options are valid under the current command but don't appear in this collection.
+ ///
public IList Options => _options ??= new (this);
internal bool HasOptions => _options?.Count > 0;
///
- /// Represents all of the subcommands for the command.
+ /// Gets all of the subcommands for the command.
///
public IList Subcommands => _subcommands ??= new(this);
internal bool HasSubcommands => _subcommands is not null && _subcommands.Count > 0;
///
- /// Validators to the command. Validators can be used
+ /// Gets the validators to the command. Validators can be used
/// to create custom validation logic.
///
public List> Validators => _validators ??= new ();
@@ -215,9 +218,9 @@ public void SetAction(Func> action)
///
/// The option to add to the command.
public void Add(Argument argument) => Arguments.Add(argument);
-
+
///
- /// Adds a to the command.
+ /// Adds an to the command.
///
/// The option to add to the command.
public void Add(Option option) => Options.Add(option);
@@ -226,17 +229,17 @@ public void SetAction(Func> action)
/// Adds a to the command.
///
/// The Command to add to the command.
- public void Add(Command command) => Subcommands.Add(command);
+ public void Add(Command command) => Subcommands.Add(command);
///
- /// Gets or sets a value that indicates whether unmatched tokens should be treated as errors. For example,
- /// if set to and an extra command or argument is provided, validation will fail.
+ /// Gets or sets a value that indicates whether unmatched tokens should be treated as errors.
///
+ /// to fail validation when an extra command or argument is provided; otherwise, .
public bool TreatUnmatchedTokensAsErrors { get; set; } = true;
///
[DebuggerStepThrough]
- [EditorBrowsable(EditorBrowsableState.Never)] // hide from intellisense, it's public for C# collection initializer
+ [EditorBrowsable(EditorBrowsableState.Never)] // hide from intellisense, it's public for C# collection initializer
IEnumerator IEnumerable.GetEnumerator() => Children.GetEnumerator();
///
diff --git a/src/System.CommandLine/Completions/SuggestDirective.cs b/src/System.CommandLine/Completions/SuggestDirective.cs
index f52a011ebe..088c16b759 100644
--- a/src/System.CommandLine/Completions/SuggestDirective.cs
+++ b/src/System.CommandLine/Completions/SuggestDirective.cs
@@ -3,7 +3,7 @@
namespace System.CommandLine.Completions;
///
-/// Enables the use of the [suggest] directive which when specified in command line input short circuits normal command handling and writes a newline-delimited list of suggestions suitable for use by most shells to provide command line completions.
+/// Enables the use of the [suggest] directive, which, when specified in command-line input, short circuits normal command handling and writes a newline-delimited list of suggestions suitable for use by most shells to provide command line completions.
///
/// The dotnet-suggest tool requires the suggest directive to be enabled for an application to provide completions.
public sealed class SuggestDirective : Directive
@@ -22,4 +22,4 @@ public override CommandLineAction? Action
set => _action = value ?? throw new ArgumentNullException(nameof(value));
}
-}
\ No newline at end of file
+}
diff --git a/src/System.CommandLine/Directive.cs b/src/System.CommandLine/Directive.cs
index a779585bd1..558fd986e1 100644
--- a/src/System.CommandLine/Directive.cs
+++ b/src/System.CommandLine/Directive.cs
@@ -8,14 +8,16 @@
namespace System.CommandLine
{
///
- /// The purpose of directives is to provide cross-cutting functionality that can apply across command-line apps.
+ /// Provides cross-cutting functionality that can apply across command-line apps.
+ ///
+ ///
/// Because directives are syntactically distinct from the app's own syntax, they can provide functionality that applies across apps.
- ///
+ ///
/// A directive must conform to the following syntax rules:
/// * It's a token on the command line that comes after the app's name but before any subcommands or options.
/// * It's enclosed in square brackets.
/// * It doesn't contain spaces.
- ///
+ ///
public class Directive : Symbol
{
///
diff --git a/src/System.CommandLine/Help/HelpAction.cs b/src/System.CommandLine/Help/HelpAction.cs
index 5566380d7e..815499c7ea 100644
--- a/src/System.CommandLine/Help/HelpAction.cs
+++ b/src/System.CommandLine/Help/HelpAction.cs
@@ -3,7 +3,7 @@
namespace System.CommandLine.Help
{
///
- /// Provides command line help.
+ /// Provides command-line help.
///
public sealed class HelpAction : SynchronousCommandLineAction
{
@@ -11,11 +11,11 @@ public sealed class HelpAction : SynchronousCommandLineAction
private int _maxWidth = -1;
///
- /// The maximum width in characters after which help output is wrapped.
+ /// Gets or sets the maximum width in characters after which help output is wrapped.
///
- /// It defaults to .
+ /// The maximum width in characters after which help output is wrapped. The default is .
public int MaxWidth
- {
+ {
get
{
if (_maxWidth < 0)
@@ -44,7 +44,7 @@ public int MaxWidth
}
///
- /// Specifies an to be used to format help output when help is requested.
+ /// Gets or sets the to use to format help output.
///
internal HelpBuilder Builder
{
@@ -68,4 +68,4 @@ public override int Invoke(ParseResult parseResult)
public override bool ClearsParseErrors => true;
}
-}
\ No newline at end of file
+}
diff --git a/src/System.CommandLine/Invocation/ParseErrorAction.cs b/src/System.CommandLine/Invocation/ParseErrorAction.cs
index 3f35c2cc1e..fd939ccfea 100644
--- a/src/System.CommandLine/Invocation/ParseErrorAction.cs
+++ b/src/System.CommandLine/Invocation/ParseErrorAction.cs
@@ -10,20 +10,20 @@
namespace System.CommandLine.Invocation;
///
-/// Provides command line output with error details in the case of a parsing error.
+/// Provides command-line output with error details in the case of a parsing error.
///
public sealed class ParseErrorAction : SynchronousCommandLineAction
{
///
- /// Indicates whether to show help along with error details when an error is found during parsing.
+ /// Gets or sets a value that indicates whether to show help along with error details when an error is found during parsing.
///
- /// When set to , indicates that help will be shown along with parse error details. When set to false, help will not be shown.
+ /// to show help along with parse error details. to not show help.
public bool ShowHelp { get; set; } = true;
///
- /// Indicates whether to show typo suggestions along with error details when an error is found during parsing.
+ /// Gets or sets a value that indicates whether to show typo suggestions along with error details when an error is found during parsing.
///
- /// When set to , indicates that suggestions will be shown along with parse error details. When set to false, suggestions will not be shown.
+ /// to show suggestions along with parse error details. to now show suggestions.
public bool ShowTypoCorrections { get; set; } = true;
///
@@ -232,4 +232,4 @@ static int GetDistance(string first, string second)
}
private const int MaxLevenshteinDistance = 3;
-}
\ No newline at end of file
+}
diff --git a/src/System.CommandLine/InvocationConfiguration.cs b/src/System.CommandLine/InvocationConfiguration.cs
index 9338503bee..3537835008 100644
--- a/src/System.CommandLine/InvocationConfiguration.cs
+++ b/src/System.CommandLine/InvocationConfiguration.cs
@@ -9,23 +9,30 @@ public class InvocationConfiguration
private TextWriter? _output, _error;
///
- /// Enables a default exception handler to catch any unhandled exceptions thrown during invocation. Enabled by default.
+ /// Gets or sets a value that indicates whether a default exception handler catches any unhandled exceptions thrown during invocation.
///
+ /// if a default exception handler catches any unhandled exceptions thrown during invocation. The default is .
public bool EnableDefaultExceptionHandler { get; set; } = true;
///
- /// Enables signaling and handling of process termination (Ctrl+C, SIGINT, SIGTERM) via a
+ /// Gets or sets a time span that enables signaling and handling of process termination (Ctrl+C, SIGINT, SIGTERM) via a
/// that can be passed to a during invocation.
- /// If not provided, a default timeout of 2 seconds is enforced.
///
- public TimeSpan? ProcessTerminationTimeout { get; set; } = TimeSpan.FromSeconds(2);
+ /// The default is two seconds.
+ ///
+ /// If this property is set to , the termination request isn't handled by System.CommandLine. In that case, the process is terminated immediately unless some other part of the program adds a handler.
+ ///
+ public TimeSpan? ProcessTerminationTimeout { get; set; } = TimeSpan.FromSeconds(2);
///
- /// The standard output. Used by Help and other facilities that write non-error information.
- /// By default it's set to .
- /// For testing purposes, it can be set to a new instance of .
- /// If you want to disable the output, please set it to .
+ /// Gets or sets the standard output.
///
+ /// The default is set to .
+ ///
+ /// The standard output is used by Help and other facilities that write non-error information.
+ /// For testing purposes, it can be set to a new instance of .
+ /// If you want to disable the output, set it to .
+ ///
public TextWriter Output
{
get => _output ??= Console.Out;
@@ -33,13 +40,15 @@ public TextWriter Output
}
///
- /// The standard error. Used for printing error information like parse errors.
- /// By default it's set to .
- /// For testing purposes, it can be set to a new instance of .
+ /// Gets or sets the standard error used for printing error information like parse errors.
///
+ /// The default is set to .
+ ///
+ /// For testing purposes, it can be set to a new instance of .
+ ///
public TextWriter Error
{
get => _error ??= Console.Error;
set => _error = value ?? throw new ArgumentNullException(nameof(value), "Use TextWriter.Null to disable the output");
}
-}
\ No newline at end of file
+}
diff --git a/src/System.CommandLine/ParseResult.cs b/src/System.CommandLine/ParseResult.cs
index 666f8256ef..eb7649a65b 100644
--- a/src/System.CommandLine/ParseResult.cs
+++ b/src/System.CommandLine/ParseResult.cs
@@ -62,17 +62,17 @@ internal ParseResult(
internal static ParseResult Empty() => new RootCommand().Parse(Array.Empty());
///
- /// A result indicating the command specified in the command line input.
+ /// Gets a result indicating the command specified in the command line input.
///
public CommandResult CommandResult { get; }
///
- /// The configuration used to produce the parse result.
+ /// Gets the configuration used to produce the parse result.
///
public ParserConfiguration Configuration { get; }
///
- /// The configuration used to specify command line runtime behavior.
+ /// Gets the configuration used to specify command line run-time behavior.
///
public InvocationConfiguration InvocationConfiguration
{
@@ -86,19 +86,19 @@ public InvocationConfiguration InvocationConfiguration
public CommandResult RootCommandResult => _rootCommandResult;
///
- /// Gets the parse errors found while parsing command line input.
+ /// Gets the parse errors found while parsing command-line input.
///
public IReadOnlyList Errors { get; }
///
- /// Gets the tokens identified while parsing command line input.
+ /// Gets the tokens identified while parsing command-line input.
///
public IReadOnlyList Tokens { get; }
///
- /// Holds the value of a complete command line input prior to splitting and tokenization, when provided.
+ /// Gets the value of a complete command line input prior to splitting and tokenization, when provided.
///
- /// This will not be set when the parser is called from Program.Main . It is primarily used when calculating suggestions via the dotnet-suggest tool.
+ /// This value will not be set when the parser is called from Program.Main . It is primarily used when calculating suggestions via the dotnet-suggest tool.
internal string? CommandLineText { get; }
///
@@ -137,9 +137,9 @@ CommandLineText is null
///
/// The name of the Symbol for which to get a value.
/// The parsed value or a configured default.
- /// Thrown when parsing resulted in parse error(s).
- /// Thrown when there was no symbol defined for given name for the parsed command.
- /// Thrown when parsed result can not be cast to .
+ /// Parsing resulted in one or more errors.
+ /// No symbol was defined for the given name for the parsed command.
+ /// The parsed result cannot be cast to .
public T? GetValue(string name)
=> RootCommandResult.GetValue(name);
@@ -148,7 +148,7 @@ CommandLineText is null
///
/// The argument for which to get a value.
/// The parsed value or a configured default.
- /// Thrown when required argument was not parsed or has no default value configured.
+ /// The required argument was not parsed or has no default value configured.
public T GetRequiredValue(Argument argument)
=> RootCommandResult.GetRequiredValue(argument);
@@ -157,18 +157,18 @@ public T GetRequiredValue(Argument argument)
///
/// The option for which to get a value.
/// The parsed value or a configured default.
- /// Thrown when required option was not parsed or has no default value configured.
+ /// The required option was not parsed or has no default value configured.
public T GetRequiredValue(Option option)
=> RootCommandResult.GetRequiredValue(option);
///
- /// Gets the parsed or default value for the specified required symbol name, in the context of parsed command (not entire symbol tree).
+ /// Gets the parsed or default value for the specified required symbol name in the context of the parsed command (not entire symbol tree).
///
- /// The name of the required Symbol for which to get a value.
+ /// The name of the required symbol for which to get a value.
/// The parsed value or a configured default.
- /// Thrown when parsing resulted in parse error(s) or required symbol was not parsed or has no default value configured.
- /// Thrown when there was no symbol defined for given name for the parsed command.
- /// Thrown when parsed result can not be cast to .
+ /// Parsing resulted in one or more errors, or the required symbol was not parsed or has no default value configured.
+ /// No symbol was defined for the given name for the parsed command.
+ /// The parsed result cannot be cast to .
public T GetRequiredValue(string name)
=> RootCommandResult.GetRequiredValue(name);
@@ -218,7 +218,7 @@ public T GetRequiredValue(string name)
/// Finds a result for a symbol having the specified name anywhere in the parse tree.
///
/// The name of the symbol for which to find a result.
- /// An symbol result if the argument was matched by the parser or has a default value; otherwise, null .
+ /// A symbol result if the argument was matched by the parser or has a default value; otherwise, null .
public SymbolResult? GetResult(string name) =>
_rootCommandResult.SymbolResultTree.GetResult(name);
@@ -270,13 +270,13 @@ static string[] OptionsWithArgumentLimitReached(CommandResult commandResult) =>
}
///
- /// Invokes the appropriate command handler for a parsed command line input.
+ /// Invokes the appropriate command handler for a parsed command-line input.
///
/// The configuration used to define invocation behaviors.
/// A token that can be used to cancel an invocation.
/// A task whose result can be used as a process exit code.
public Task InvokeAsync(
- InvocationConfiguration? configuration = null,
+ InvocationConfiguration? configuration = null,
CancellationToken cancellationToken = default)
{
if (configuration is not null)
@@ -288,7 +288,7 @@ public Task InvokeAsync(
}
///
- /// Invokes the appropriate command handler for a parsed command line input.
+ /// Invokes the appropriate command handler for a parsed command-line input.
///
/// The configuration used to define invocation behaviors.
/// A value that can be used as a process exit code.
@@ -400,4 +400,4 @@ static bool WillAcceptAnArgument(
}
}
}
-}
\ No newline at end of file
+}
diff --git a/src/System.CommandLine/ParserConfiguration.cs b/src/System.CommandLine/ParserConfiguration.cs
index c3a8b06145..f1f221236a 100644
--- a/src/System.CommandLine/ParserConfiguration.cs
+++ b/src/System.CommandLine/ParserConfiguration.cs
@@ -11,17 +11,17 @@ namespace System.CommandLine
public class ParserConfiguration
{
///
- /// Enables the parser to recognize and expand POSIX-style bundled options.
+ /// Gets or sets a value that indicates whether the parser recognizes and expands POSIX-style bundled options.
///
/// to parse POSIX bundles; otherwise, .
///
/// POSIX conventions recommend that single-character options be allowed to be specified together after a single - prefix. When is set to , the following command lines are equivalent:
- ///
+ ///
///
/// > myapp -a -b -c
/// > myapp -abc
///
- ///
+ ///
/// If an argument is provided after an option bundle, it applies to the last option in the bundle. When is set to , all of the following command lines are equivalent:
///
/// > myapp -a -b -c arg
@@ -33,12 +33,12 @@ public class ParserConfiguration
public bool EnablePosixBundling { get; set; } = true;
///
- /// Response file token replacer, enabled by default.
- /// To disable response files support, this property needs to be set to null.
+ /// Gets or sets the response file token replacer.
///
+ /// to disable response files support. By default, the response file token replacer is enabled.
///
- /// When enabled, any token prefixed with @ can be replaced with zero or more other tokens. This is mostly commonly used to expand tokens from response files and interpolate them into a command line prior to parsing.
+ /// When enabled, any token prefixed with @ can be replaced with zero or more other tokens. This is mostly commonly used to expand tokens from response files and interpolate them into a command line prior to parsing.
///
public TryReplaceToken? ResponseFileTokenReplacer { get; set; } = StringExtensions.TryReadResponseFile;
}
-}
\ No newline at end of file
+}
diff --git a/src/System.CommandLine/Parsing/ArgumentResult.cs b/src/System.CommandLine/Parsing/ArgumentResult.cs
index f076baa32f..f7d091fa93 100644
--- a/src/System.CommandLine/Parsing/ArgumentResult.cs
+++ b/src/System.CommandLine/Parsing/ArgumentResult.cs
@@ -7,7 +7,7 @@
namespace System.CommandLine.Parsing
{
///
- /// A result produced when parsing an .
+ /// Represents a result produced when parsing an .
///
public sealed class ArgumentResult : SymbolResult
{
@@ -23,7 +23,7 @@ internal ArgumentResult(
}
///
- /// The argument to which the result applies.
+ /// Gets the argument to which the result applies.
///
public Argument Argument { get; }
@@ -37,19 +37,19 @@ internal ArgumentConversionResult GetArgumentConversionResult() =>
///
/// Gets the parsed value or the default value for .
///
- /// The parsed value or the default value for
+ /// The parsed value or the default value for .
public T GetValueOrDefault() =>
(_conversionResult ??= ValidateAndConvert(useValidators: false))
.ConvertIfNeeded(typeof(T))
.GetValueOrDefault();
///
- /// Specifies the maximum number of tokens to consume for the argument. Remaining tokens are passed on and can be consumed by later arguments, or will otherwise be added to
+ /// Specifies the maximum number of tokens to consume for the argument. Remaining tokens are passed on and can be consumed by later arguments, or will otherwise be added to .
///
/// The number of tokens to take. The rest are passed on.
- /// numberOfTokens - Value must be at least 1.
- /// Thrown if this method is called more than once.
- /// Thrown if this method is called by Option-owned ArgumentResult.
+ /// numberOfTokens - Value must be at least 1.
+ /// This method is called more than once.
+ /// This method is called by an Option-owned .
public void OnlyTake(int numberOfTokens)
{
if (numberOfTokens < 0)
@@ -200,7 +200,7 @@ private ArgumentConversionResult ValidateAndConvert(bool useValidators)
ArgumentConversionResult.ArgumentConversionCannotParse(
this,
Argument.ValueType,
- Tokens.Count > 0
+ Tokens.Count > 0
? Tokens[0].Value
: ""));
@@ -218,7 +218,7 @@ ArgumentConversionResult ReportErrorIfNeeded(ArgumentConversionResult result)
///
/// Since Option.Argument is an internal implementation detail, this ArgumentResult applies to the OptionResult in public API if the parent is an OptionResult.
///
- private SymbolResult AppliesToPublicSymbolResult =>
+ private SymbolResult AppliesToPublicSymbolResult =>
Parent is OptionResult optionResult ? optionResult : this;
}
}
diff --git a/src/System.CommandLine/Parsing/CommandResult.cs b/src/System.CommandLine/Parsing/CommandResult.cs
index ae4bd2922f..6fbb4ee779 100644
--- a/src/System.CommandLine/Parsing/CommandResult.cs
+++ b/src/System.CommandLine/Parsing/CommandResult.cs
@@ -7,7 +7,7 @@
namespace System.CommandLine.Parsing
{
///
- /// A result produced when parsing a .
+ /// Represents a result produced when parsing a .
///
public sealed class CommandResult : SymbolResult
{
@@ -23,17 +23,17 @@ internal CommandResult(
}
///
- /// The command to which the result applies.
+ /// Gets the command to which the result applies.
///
public Command Command { get; }
///
- /// The token that was parsed to specify the command.
+ /// Gets the token that was parsed to specify the command.
///
public Token IdentifierToken { get; }
///
- /// Child symbol results in the parse tree.
+ /// Gets the child symbol results in the parse tree.
///
public IEnumerable Children => SymbolResultTree.GetChildren(this);
diff --git a/src/System.CommandLine/Parsing/DirectiveResult.cs b/src/System.CommandLine/Parsing/DirectiveResult.cs
index 78ceeaf0d7..925ec3e3e6 100644
--- a/src/System.CommandLine/Parsing/DirectiveResult.cs
+++ b/src/System.CommandLine/Parsing/DirectiveResult.cs
@@ -3,7 +3,7 @@
namespace System.CommandLine.Parsing
{
///
- /// A result produced when parsing an .
+ /// Represents a result produced when parsing a .
///
public sealed class DirectiveResult : SymbolResult
{
@@ -17,18 +17,18 @@ internal DirectiveResult(Directive directive, Token token, SymbolResultTree symb
}
///
- /// Parsed values of [name:value] directive(s).
+ /// Parsed values of [name:value] directives.
///
- /// Can be empty for [name] directives.
+ /// Can be empty for [name] directives.
public IReadOnlyList Values => _values is null ? Array.Empty() : _values;
///
- /// The directive to which the result applies.
+ /// Gets the directive to which the result applies.
///
public Directive Directive { get; }
///
- /// The token that was parsed to specify the directive.
+ /// Gets the token that was parsed to specify the directive.
///
public Token Token { get; }
diff --git a/src/System.CommandLine/Parsing/OptionResult.cs b/src/System.CommandLine/Parsing/OptionResult.cs
index c673a90458..7aa91c0fc3 100644
--- a/src/System.CommandLine/Parsing/OptionResult.cs
+++ b/src/System.CommandLine/Parsing/OptionResult.cs
@@ -7,7 +7,7 @@
namespace System.CommandLine.Parsing
{
///
- /// A result produced when parsing an .
+ /// Represents a result produced when parsing an .
///
public sealed class OptionResult : SymbolResult
{
@@ -25,24 +25,24 @@ internal OptionResult(
}
///
- /// The option to which the result applies.
+ /// Gets the option to which the result applies.
///
public Option Option { get; }
///
- /// Indicates whether the result was created implicitly and not due to the option being specified on the command line.
+ /// Gets a value that indicates whether the result was created implicitly and not due to the option being specified on the command line.
///
/// Implicit results commonly result from options having a default value.
public bool Implicit => IdentifierToken is null || IdentifierToken.Implicit;
///
- /// The token that was parsed to specify the option.
+ /// Gets the token that was parsed to specify the option.
///
/// An identifier token is a token that matches either the option's name or one of its aliases.
public Token? IdentifierToken { get; }
///
- /// The number of occurrences of an identifier token matching the option.
+ /// Gets the number of occurrences of an identifier token matching the option.
///
public int IdentifierTokenCount { get; internal set; }
diff --git a/src/System.CommandLine/Parsing/SymbolResult.cs b/src/System.CommandLine/Parsing/SymbolResult.cs
index 18df4af83e..6d275887c6 100644
--- a/src/System.CommandLine/Parsing/SymbolResult.cs
+++ b/src/System.CommandLine/Parsing/SymbolResult.cs
@@ -6,7 +6,7 @@
namespace System.CommandLine.Parsing
{
///
- /// A result produced during parsing for a specific symbol.
+ /// Represents a result produced during parsing for a specific symbol.
///
public abstract class SymbolResult
{
@@ -20,7 +20,7 @@ private protected SymbolResult(SymbolResultTree symbolResultTree, SymbolResult?
}
///
- /// The parse errors associated with this symbol result.
+ /// Gets the parse errors associated with this symbol result.
///
public IEnumerable Errors
{
@@ -45,21 +45,21 @@ public IEnumerable Errors
}
///
- /// The parent symbol result in the parse tree.
+ /// Gets the parent symbol result in the parse tree.
///
public SymbolResult? Parent { get; }
///
- /// The list of tokens associated with this symbol result during parsing.
+ /// Gets the list of tokens associated with this symbol result during parsing.
///
public IReadOnlyList Tokens => _tokens is not null ? _tokens : Array.Empty();
internal void AddToken(Token token) => (_tokens ??= new()).Add(token);
///
- /// Adds an error message for this symbol result to it's parse tree.
+ /// Adds an error message for this symbol result to its parse tree.
///
- /// Setting an error will cause the parser to indicate an error for the user and prevent invocation of the command line.
+ /// Setting an error causes the parser to indicate an error for the user and prevents invocation of the command line.
public virtual void AddError(string errorMessage) => SymbolResultTree.AddError(new ParseError(errorMessage, this));
///
@@ -73,7 +73,7 @@ public IEnumerable Errors
/// Finds a result for the specific command anywhere in the parse tree, including parent and child symbol results.
///
/// The command for which to find a result.
- /// An command result if the command was matched by the parser; otherwise, null .
+ /// A command result if the command was matched by the parser; otherwise, null .
public CommandResult? GetResult(Command command) => SymbolResultTree.GetResult(command);
///
@@ -87,7 +87,7 @@ public IEnumerable Errors
/// Finds a result for the specific directive anywhere in the parse tree.
///
/// The directive for which to find a result.
- /// A directive result if the directive was matched by the parser, null otherwise.
+ /// A directive result if the directive was matched by the parser; otherwise, null .
public DirectiveResult? GetResult(Directive directive) => SymbolResultTree.GetResult(directive);
///
@@ -98,7 +98,7 @@ public IEnumerable Errors
/// A if the was matched by the parser or has a default value;
/// otherwise, .
///
- public SymbolResult? GetResult(string name) =>
+ public SymbolResult? GetResult(string name) =>
SymbolResultTree.GetResult(name);
///
diff --git a/src/System.CommandLine/System.Runtime.CompilerServices/Range.cs b/src/System.CommandLine/System.Runtime.CompilerServices/Range.cs
index 01342202b7..617fd90d8e 100644
--- a/src/System.CommandLine/System.Runtime.CompilerServices/Range.cs
+++ b/src/System.CommandLine/System.Runtime.CompilerServices/Range.cs
@@ -8,11 +8,11 @@
namespace System
{
- /// Represent a type can be used to index a collection either from the start or the end.
+ /// Represents a type that can be used to index a collection either from the beginning or the end.
///
- /// Index is used by the C# compiler to support the new index syntax
- ///
- /// int[] someArray = new int[5] { 1, 2, 3, 4, 5 } ;
+ /// is used by the C# compiler to support the >^ or ["index from end" operator](https://learn.microsoft.com/dotnet/csharp/language-reference/operators/member-access-operators#index-from-end-operator-):
+ ///
+ /// int[] someArray = new int[5] { 1, 2, 3, 4, 5 };
/// int lastElement = someArray[^1]; // lastElement = 5
///
///
@@ -20,11 +20,11 @@ namespace System
{
private readonly int _value;
- /// Construct an Index using a value and indicating if the index is from the start or from the end.
- /// The index value. it has to be zero or positive number.
- /// Indicating if the index is from the start or from the end.
+ /// Initializes a new with a specified index position and a value that indicates if the index is from the beginning or the end of a collection.
+ /// The index value. It has to be greater then or equal to zero.
+ /// to index from the end of the collection, or to index from the beginning of the collection.
///
- /// If the Index constructed from the end, index value 1 means pointing at the last element and index value 0 means pointing at beyond last element.
+ /// If the is constructed from the end, an index value of 1 points to the last element, and an index value of 0 points beyond the last element.
///
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public Index(int value, bool fromEnd = false)
@@ -46,14 +46,17 @@ private Index(int value)
_value = value;
}
- /// Create an Index pointing at first element.
+ /// Gets an that points to the first element of a collection.
+ /// An instance that points to the first element of a collection.
public static Index Start => new Index(0);
- /// Create an Index pointing at beyond last element.
+ /// Gets an that points beyond the last element.
+ /// An index that points beyond the last element.
public static Index End => new Index(~0);
- /// Create an Index from the start at the position indicated by the value.
- /// The index value from the start.
+ /// Creates an from the specified index at the start of a collection.
+ /// The index position from the start of a collection.
+ /// The index value.
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static Index FromStart(int value)
{
@@ -65,8 +68,8 @@ public static Index FromStart(int value)
return new Index(value);
}
- /// Create an Index from the end at the position indicated by the value.
- /// The index value from the end.
+ /// Creates an from the end of a collection at a specified index position.
+ /// The index value from the end of a collection.
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static Index FromEnd(int value)
{
@@ -78,7 +81,8 @@ public static Index FromEnd(int value)
return new Index(~value);
}
- /// Returns the index value.
+ /// Gets the index value.
+ /// The index value.
public int Value
{
get
@@ -94,18 +98,18 @@ public int Value
}
}
- /// Indicates whether the index is from the start or the end.
+ /// Gets a value that indicates whether the index is from the start or the end.
+ /// if the Index is from the end; otherwise, .
public bool IsFromEnd => _value < 0;
- /// Calculate the offset from the start using the giving collection length.
- /// The length of the collection that the Index will be used with. length has to be a positive value
+ /// Calculates the offset from the start of the collection using the specified collection length.
+ /// The length of the collection that the Index will be used with. Must be a positive value.
+ /// The offset.
///
- /// For performance reason, we don't validate the input length parameter and the returned offset value against negative values.
- /// we don't validate either the returned offset is greater than the input length.
- /// It is expected Index will be used with collections which always have non negative length/count. If the returned offset is negative and
- /// then used to index a collection will get out of range exception which will be same affect as the validation.
+ /// For performance reasons, this method does not validate if length or the returned value are negative. It also doesn't validate if the returned value is greater than length .
+ /// Collections aren't expected to have a negative length/count. If this method's returned offset is negative and is then used to index a collection, the runtime will throw , which will have the same effect as validation.
///
- [MethodImpl(MethodImplOptions.AggressiveInlining)]
+ [MethodImpl(MethodImplOptions.AggressiveInlining)]
public int GetOffset(int length)
{
var offset = _value;
@@ -120,21 +124,27 @@ public int GetOffset(int length)
return offset;
}
- /// Indicates whether the current Index object is equal to another object of the same type.
- /// An object to compare with this object
+ /// Indicates whether the current Index object is equal to a specified object.
+ /// An object to compare with this instance.
+ /// if is of type and is equal to the current instance; otherwise, .
public override bool Equals(object? value) => value is Index && _value == ((Index)value)._value;
- /// Indicates whether the current Index object is equal to another Index object.
- /// An object to compare with this object
+ /// Returns a value that indicates whether the current object is equal to another object.
+ /// The object to compare with this instance.
+ /// if the current Index object is equal to ; otherwise, .
public bool Equals(Index other) => _value == other._value;
/// Returns the hash code for this instance.
+ /// The hash code.
public override int GetHashCode() => _value;
- /// Converts integer number to an Index.
+ /// Converts an integer number to an .
+ /// The integer to convert.
+ /// An index representing the integer.
public static implicit operator Index(int value) => FromStart(value);
- /// Converts the value of the current Index object to its equivalent string representation.
+ /// Returns the string representation of the current instance.
+ /// The string representation of the .
public override string ToString()
{
if (IsFromEnd)
@@ -144,10 +154,10 @@ public override string ToString()
}
}
- /// Represent a range has start and end indexes.
+ /// Represents a range that has start and end indexes.
///
- /// Range is used by the C# compiler to support the range syntax.
- ///
+ /// is used by the C# compiler to support the range syntax:
+ ///
/// int[] someArray = new int[5] { 1, 2, 3, 4, 5 };
/// int[] subArray1 = someArray[0..2]; // { 1, 2 }
/// int[] subArray2 = someArray[1..^0]; // { 2, 3, 4, 5 }
@@ -155,59 +165,69 @@ public override string ToString()
///
internal readonly struct Range : IEquatable
{
- /// Represent the inclusive start index of the Range.
+ /// Gets the inclusive start index of the .
+ /// The inclusive start index of the range.
public Index Start { get; }
- /// Represent the exclusive end index of the Range.
+ /// Gets an that represents the exclusive end index of the range.
+ /// The end index of the range.
public Index End { get; }
- /// Construct a Range object using the start and end indexes.
- /// Represent the inclusive start index of the range.
- /// Represent the exclusive end index of the range.
+ /// Instantiates a new instance with the specified starting and ending indexes.
+ /// The inclusive start index of the range.
+ /// The exclusive end index of the range.
public Range(Index start, Index end)
{
Start = start;
End = end;
}
- /// Indicates whether the current Range object is equal to another object of the same type.
- /// An object to compare with this object
+ /// Returns a value that indicates whether the current instance is equal to a specified object.
+ /// An object to compare with this object.
+ /// if is of type and is equal to the current instance; otherwise, .
public override bool Equals(object? value) =>
value is Range r &&
r.Start.Equals(Start) &&
r.End.Equals(End);
- /// Indicates whether the current Range object is equal to another Range object.
- /// An object to compare with this object
+ /// Returns a value that indicates whether the current instance is equal to another object.
+ /// A object to compare with this object.
+ /// if the current instance is equal to ; otherwise, .
public bool Equals(Range other) => other.Start.Equals(Start) && other.End.Equals(End);
/// Returns the hash code for this instance.
+ /// The hash code.
public override int GetHashCode()
{
return Start.GetHashCode() * 31 + End.GetHashCode();
}
- /// Converts the value of the current Range object to its equivalent string representation.
+ /// Returns the string representation of the current object.
+ /// The string representation of the range.
public override string ToString()
{
return Start + ".." + End;
}
- /// Create a Range object starting from start index to the end of the collection.
+ /// Returns a new instance starting from a specified start index to the end of the collection.
+ /// The position of the first element from which the Range will be created.
+ /// A range from to the end of the collection.
public static Range StartAt(Index start) => new Range(start, Index.End);
- /// Create a Range object starting from first element in the collection to the end Index.
+ /// Creates a object starting from the first element in the collection to a specified end index.
+ /// The position of the last element up to which the object will be created.
+ /// A range that starts from the first element to .
public static Range EndAt(Index end) => new Range(Index.Start, end);
- /// Create a Range object starting from first element to the end.
+ /// Gets a object that starts from the first element to the end.
+ /// A range from the start to the end.
public static Range All => new Range(Index.Start, Index.End);
- /// Calculate the start offset and length of range object using a collection length.
- /// The length of the collection that the range will be used with. length has to be a positive value.
+ /// Calculates the start offset and length of the range object using a collection length.
+ /// A positive integer that represents the length of the collection that the range will be used with.
+ /// The start offset and length of the range.
///
- /// For performance reason, we don't validate the input length parameter against negative values.
- /// It is expected Range will be used with collections which always have non negative length/count.
- /// We validate the range is inside the length scope though.
+ /// For performance reasons, this method doesn't validate to ensure that it is not negative. It does ensure that is within the current instance.
///
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public (int Offset, int Length) GetOffsetAndLength(int length)
diff --git a/src/System.CommandLine/VersionOption.cs b/src/System.CommandLine/VersionOption.cs
index dfcf51f86a..cc4795e8c9 100644
--- a/src/System.CommandLine/VersionOption.cs
+++ b/src/System.CommandLine/VersionOption.cs
@@ -9,22 +9,28 @@
namespace System.CommandLine
{
///
- /// A standard option that indicates that version information should be displayed for the app.
+ /// Represents a standard option that indicates that version information should be displayed for the app.
///
public sealed class VersionOption : Option
{
private CommandLineAction? _action;
///
- /// When added to a , it enables the use of a --version option, which when specified in command line input will short circuit normal command handling and instead write out version information before exiting.
+ /// Initializes a new instance of .
///
+ ///
+ /// When added to a , it enables the use of a --version option, which, when specified in command line input, short circuits normal command handling and instead writes out version information before exiting.
+ ///
public VersionOption() : this("--version")
{
}
///
- /// When added to a , it enables the use of a provided option name and aliases, which when specified in command line input will short circuit normal command handling and instead write out version information before exiting.
+ /// Initializes a new instance of .
///
+ ///
+ /// When added to a , it enables the use of a provided option name and aliases, which, when specified in command line input, short circuits normal command handling and instead writes out version information before exiting.
+ ///
public VersionOption(string name, params string[] aliases)
: base(name, aliases)
{
@@ -88,4 +94,4 @@ private static string GetExecutableVersion()
}
}
}
-}
\ No newline at end of file
+}