From f2de092e8d11f85526f8409563e328784b98a231 Mon Sep 17 00:00:00 2001
From: Genevieve Warren <24882762+gewarren@users.noreply.github.com>
Date: Thu, 16 Oct 2025 20:56:05 -0700
Subject: [PATCH 1/6] docs improvements
---
src/System.CommandLine/Argument.cs | 20 +--
src/System.CommandLine/Argument{T}.cs | 14 +-
src/System.CommandLine/Command.cs | 26 ++--
.../Completions/SuggestDirective.cs | 4 +-
src/System.CommandLine/Directive.cs | 8 +-
src/System.CommandLine/Help/HelpAction.cs | 12 +-
.../Invocation/ParseErrorAction.cs | 12 +-
.../InvocationConfiguration.cs | 30 +++--
src/System.CommandLine/ParseResult.cs | 40 +++---
src/System.CommandLine/ParserConfiguration.cs | 12 +-
.../Parsing/ArgumentResult.cs | 16 +--
.../Parsing/CommandResult.cs | 8 +-
.../Parsing/DirectiveResult.cs | 10 +-
.../Parsing/OptionResult.cs | 10 +-
.../Parsing/SymbolResult.cs | 18 +--
src/System.CommandLine/System.CommandLine.sln | 24 ++++
.../System.Runtime.CompilerServices/Range.cs | 120 ++++++++++--------
src/System.CommandLine/VersionOption.cs | 14 +-
18 files changed, 228 insertions(+), 170 deletions(-)
create mode 100644 src/System.CommandLine/System.CommandLine.sln
diff --git a/src/System.CommandLine/Argument.cs b/src/System.CommandLine/Argument.cs
index f1c915045e..8e297c2ccf 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.
///
- /// < and > ).
///
+ ///
+ /// The name to show as the placeholder for the argument's value.
+ ///
///
- /// If null , the null , the
///
/// An argument with argument and a
@@ -57,9 +60,6 @@ public ArgumentArity Arity
/// <Value> . If <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
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..2fed770b15 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 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
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
public Func? CustomParser
diff --git a/src/System.CommandLine/Command.cs b/src/System.CommandLine/Command.cs
index be565651d2..4d8e9cc5be 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
- /// 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 dotnet run uses run as the command.
///
public class Command : Symbol, IEnumerable
{
@@ -57,28 +57,28 @@ 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, including inherited options that have been applied to any of the command's ancestors.
///
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 +215,9 @@ public void SetAction(Func> action)
///
///
- /// Adds a
/// > action)
/// Adds a
- /// Gets or sets a value that indicates whether unmatched tokens should be treated as errors. For example,
- /// if set to
+ ///
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
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 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
+ ///
- /// 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.
///
+ ///
- /// Enables signaling and handling of process termination (Ctrl+C, SIGINT, SIGTERM) via a
- public TimeSpan? ProcessTerminationTimeout { get; set; } = TimeSpan.FromSeconds(2);
+ /// The default is two seconds.
+ 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
+ /// 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
public TextWriter Output
{
get => _output ??= Console.Out;
@@ -33,13 +37,15 @@ public TextWriter Output
}
///
- /// The standard error. Used for printing error information like parse errors.
- /// By default it's set to
+ /// 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..19d402decc 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 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 symbolw 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 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,7 +157,7 @@ public T GetRequiredValue(Argument argument)
///
/// 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);
@@ -166,9 +166,9 @@ public T GetRequiredValue(Option option)
///
/// 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 given name for the parsed command.
+ /// The parsed result can't 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.
///
/// 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.
///
/// 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.
///
/// 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..ed98cbaa7e 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.
///
///
/// POSIX conventions recommend that single-character options be allowed to be specified together after a single - prefix. When
/// > 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
/// > 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.
///
+ ///
/// 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..f42ac1af44 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
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,7 +37,7 @@ 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))
@@ -47,9 +47,9 @@ public 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 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 Option-owned ArgumentResult.
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
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
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
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.
///
/// 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.
///
/// 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 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 } ;
+ /// >^ 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.
- /// Initializes a new
+ ///
- /// 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
[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
+ /// 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
+ /// 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.
- /// Creates an
+ /// 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.
- /// Creates an
+ /// 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.
+ /// Calculate the offset from the start using the giving collection length.
- /// Calculates the offset from the start of the collection using the specified collection length.
+ /// 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
- [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.
- /// Indicates whether the current Index object is equal to a specified object.
+ /// Indicates whether the current Index object is equal to another Index object.
- /// Returns a value that indicates whether the current object is equal to another
+ /// 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
+ /// 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
+ /// 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.
- ///
+ ///
/// 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
+ /// The end index of the range.
public Index End { get; }
- /// Construct a Range object using the start and end indexes.
- /// Instantiates a new
+ /// Indicates whether the current Range object is equal to another object of the same type.
- /// Returns a value that indicates whether the current instance is equal to a specified object.
+ /// Indicates whether the current Range object is equal to another Range object.
- /// Returns a value that indicates whether the current instance is equal to another
+ /// 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
+ /// 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
+ /// A range from
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
+ /// 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
+ /// 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.
- /// Calculates the start offset and length of the range object using a collection length.
+ /// 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
[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..4322788106 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 --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 --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
+ ///
+ /// When added to a
public VersionOption(string name, params string[] aliases)
: base(name, aliases)
{
@@ -88,4 +94,4 @@ private static string GetExecutableVersion()
}
}
}
-}
\ No newline at end of file
+}
From 0c105c46caa9bc32246085b2d2d5ba39e3acd7e7 Mon Sep 17 00:00:00 2001
From: Genevieve Warren <24882762+gewarren@users.noreply.github.com>
Date: Thu, 16 Oct 2025 21:08:58 -0700
Subject: [PATCH 2/6] don't commit solution file
---
src/System.CommandLine/System.CommandLine.sln | 24 -------------------
1 file changed, 24 deletions(-)
delete mode 100644 src/System.CommandLine/System.CommandLine.sln
diff --git a/src/System.CommandLine/System.CommandLine.sln b/src/System.CommandLine/System.CommandLine.sln
deleted file mode 100644
index cc9f8a6a2a..0000000000
--- a/src/System.CommandLine/System.CommandLine.sln
+++ /dev/null
@@ -1,24 +0,0 @@
-Microsoft Visual Studio Solution File, Format Version 12.00
-# Visual Studio Version 17
-VisualStudioVersion = 17.5.2.0
-MinimumVisualStudioVersion = 10.0.40219.1
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "System.CommandLine", "System.CommandLine.csproj", "{CE3D4493-BFD2-2940-DF44-9021C8241306}"
-EndProject
-Global
- GlobalSection(SolutionConfigurationPlatforms) = preSolution
- Debug|Any CPU = Debug|Any CPU
- Release|Any CPU = Release|Any CPU
- EndGlobalSection
- GlobalSection(ProjectConfigurationPlatforms) = postSolution
- {CE3D4493-BFD2-2940-DF44-9021C8241306}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
- {CE3D4493-BFD2-2940-DF44-9021C8241306}.Debug|Any CPU.Build.0 = Debug|Any CPU
- {CE3D4493-BFD2-2940-DF44-9021C8241306}.Release|Any CPU.ActiveCfg = Release|Any CPU
- {CE3D4493-BFD2-2940-DF44-9021C8241306}.Release|Any CPU.Build.0 = Release|Any CPU
- EndGlobalSection
- GlobalSection(SolutionProperties) = preSolution
- HideSolutionNode = FALSE
- EndGlobalSection
- GlobalSection(ExtensibilityGlobals) = postSolution
- SolutionGuid = {9E85227C-3755-4CD8-9225-E9592EF59391}
- EndGlobalSection
-EndGlobal
From 336be3b1db0afac8d1b6b2baeb40b89412aa67bb Mon Sep 17 00:00:00 2001
From: Genevieve Warren <24882762+gewarren@users.noreply.github.com>
Date: Fri, 17 Oct 2025 08:59:00 -0700
Subject: [PATCH 3/6] respond to feedback
---
src/System.CommandLine/Argument.cs | 4 +-
src/System.CommandLine/Argument{T}.cs | 2 +-
.../InvocationConfiguration.cs | 3 ++
src/System.CommandLine/ParseResult.cs | 10 ++--
src/System.CommandLine/ParserConfiguration.cs | 2 +-
.../Parsing/ArgumentResult.cs | 4 +-
.../System.Runtime.CompilerServices/Range.cs | 54 +++++++++----------
src/System.CommandLine/VersionOption.cs | 4 +-
8 files changed, 43 insertions(+), 40 deletions(-)
diff --git a/src/System.CommandLine/Argument.cs b/src/System.CommandLine/Argument.cs
index 8e297c2ccf..af2937f055 100644
--- a/src/System.CommandLine/Argument.cs
+++ b/src/System.CommandLine/Argument.cs
@@ -22,7 +22,7 @@ public abstract class Argument : Symbol
///
/// Initializes a new instance of the Argument class.
///
- /// >> CompletionSour
///
/// Gets the default value for the argument.
///
- /// The default value for the argument, if defined; otherwise, .
+ /// The default value for the argument, if defined; otherwise,
public object? GetDefaultValue()
{
var command = Parents.FlattenBreadthFirst(x => x.Parents)
diff --git a/src/System.CommandLine/Argument{T}.cs b/src/System.CommandLine/Argument{T}.cs
index 2fed770b15..999ac5604f 100644
--- a/src/System.CommandLine/Argument{T}.cs
+++ b/src/System.CommandLine/Argument{T}.cs
@@ -15,7 +15,7 @@ public class Argument : Argument
///
/// Initializes a new instance of the Argument class.
///
- ///
/// The default is two seconds.
+ ///
+ /// If this property is set to
public TimeSpan? ProcessTerminationTimeout { get; set; } = TimeSpan.FromSeconds(2);
///
diff --git a/src/System.CommandLine/ParseResult.cs b/src/System.CommandLine/ParseResult.cs
index 19d402decc..eb7649a65b 100644
--- a/src/System.CommandLine/ParseResult.cs
+++ b/src/System.CommandLine/ParseResult.cs
@@ -138,7 +138,7 @@ CommandLineText is null
/// The parsed value or a configured default.
/// Parsing resulted in one or more errors.
- /// No symbolw was defined for the given name for the parsed command.
+ /// 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);
@@ -162,13 +162,13 @@ 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 parsed value or a configured default.
/// 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 given name for the parsed command.
- /// The parsed result can't be cast to
+ /// 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);
diff --git a/src/System.CommandLine/ParserConfiguration.cs b/src/System.CommandLine/ParserConfiguration.cs
index ed98cbaa7e..f1f221236a 100644
--- a/src/System.CommandLine/ParserConfiguration.cs
+++ b/src/System.CommandLine/ParserConfiguration.cs
@@ -37,7 +37,7 @@ public class ParserConfiguration
///
///
- /// 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;
}
diff --git a/src/System.CommandLine/Parsing/ArgumentResult.cs b/src/System.CommandLine/Parsing/ArgumentResult.cs
index f42ac1af44..f7d091fa93 100644
--- a/src/System.CommandLine/Parsing/ArgumentResult.cs
+++ b/src/System.CommandLine/Parsing/ArgumentResult.cs
@@ -44,12 +44,12 @@ public T GetValueOrDefault() =>
.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
/// numberOfTokens - Value must be at least 1.This method is called more than once.
- /// This method is called by Option-owned ArgumentResult.
+ /// This method is called by an Option-owned
public void OnlyTake(int numberOfTokens)
{
if (numberOfTokens < 0)
diff --git a/src/System.CommandLine/System.Runtime.CompilerServices/Range.cs b/src/System.CommandLine/System.Runtime.CompilerServices/Range.cs
index f82c898438..617fd90d8e 100644
--- a/src/System.CommandLine/System.Runtime.CompilerServices/Range.cs
+++ b/src/System.CommandLine/System.Runtime.CompilerServices/Range.cs
@@ -10,7 +10,7 @@ namespace System
{
/// Represents a type that can be used to index a collection either from the beginning or the end.
///
- /// >^ or ["index from end" operator](https://learn.microsoft.com/dotnet/csharp/language-reference/operators/member-access-operators#index-from-end-operator-):
+ /// >^ 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;
- /// Initializes a new
+ /// Initializes a new
///
- /// If the
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public Index(int value, bool fromEnd = false)
@@ -46,15 +46,15 @@ private Index(int value)
_value = value;
}
- /// Gets an
+ /// Gets an
/// An instance that points to the first element of a collection.
public static Index Start => new Index(0);
- /// Gets an
+ /// Gets an
/// An index that points beyond the last element.
public static Index End => new Index(~0);
- /// Creates an
+ /// Creates an
/// The index value.
[MethodImpl(MethodImplOptions.AggressiveInlining)]
@@ -68,7 +68,7 @@ public static Index FromStart(int value)
return new Index(value);
}
- /// Creates an
+ /// Creates an
/// The offset.
///
/// 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
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public int GetOffset(int length)
@@ -126,10 +126,10 @@ public int GetOffset(int length)
/// Indicates whether the current Index object is equal to a specified object.
/// Returns a value that indicates whether the current object is equal to another
+ /// Returns a value that indicates whether the current object is equal to another
/// The hash code.
public override int GetHashCode() => _value;
- /// Converts an integer number to an
+ /// Converts an integer number to an
/// An index representing the integer.
public static implicit operator Index(int value) => FromStart(value);
- /// Returns the string representation of the current
- /// The string representation of the
+ /// Returns the string representation of the current
+ /// The string representation of the
public override string ToString()
{
if (IsFromEnd)
@@ -156,7 +156,7 @@ public override string ToString()
/// Represents a range that has start and end indexes.
///
- ///
/// int[] someArray = new int[5] { 1, 2, 3, 4, 5 };
/// int[] subArray1 = someArray[0..2]; // { 1, 2 }
@@ -165,15 +165,15 @@ public override string ToString()
///
internal readonly struct Range : IEquatable
{
- /// Gets the inclusive start index of the
+ /// Gets the inclusive start index of the
/// The inclusive start index of the range.
public Index Start { get; }
- /// Gets an
+ /// Gets an
/// The end index of the range.
public Index End { get; }
- /// Instantiates a new
+ /// Instantiates a new
/// Returns a value that indicates whether the current instance is equal to a specified object.
- /// Returns a value that indicates whether the current instance is equal to another
- /// Returns a value that indicates whether the current instance is equal to another
+ /// Returns the string representation of the current
+ /// Returns the string representation of the current
/// The string representation of the range.
public override string ToString()
{
return Start + ".." + End;
}
- /// Returns a new
+ /// Returns a new
/// A range from
public static Range StartAt(Index start) => new Range(start, Index.End);
- /// Creates a
- /// Creates a
+ /// A range that starts from the first element to
public static Range EndAt(Index end) => new Range(Index.Start, end);
- /// Gets a
+ /// Gets a
/// A range from the start to the end.
public static Range All => new Range(Index.Start, Index.End);
@@ -227,7 +227,7 @@ public override string ToString()
/// The start offset and length of the range.
///
- /// For performance reasons, this method doesn't validate
[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 4322788106..cc4795e8c9 100644
--- a/src/System.CommandLine/VersionOption.cs
+++ b/src/System.CommandLine/VersionOption.cs
@@ -16,7 +16,7 @@ public sealed class VersionOption : Option
private CommandLineAction? _action;
///
- /// Initializes a new instance of
///
/// When added to a --version option, which, when specified in command line input, short circuits normal command handling and instead writes out version information before exiting.
@@ -26,7 +26,7 @@ public VersionOption() : this("--version")
}
///
- /// Initializes a new instance of
///
/// When added to a Children
internal bool HasArguments => _arguments?.Count > 0 ;
///
- /// Gets all of the options for the command, including inherited options that have been applied to any of the command's ancestors.
+ /// Gets all of the options for the command.
///
public IList Options => _options ??= new (this);
From 7c2bef4fa3d4fe621b694af43cd767eabae1bc87 Mon Sep 17 00:00:00 2001
From: Genevieve Warren <24882762+gewarren@users.noreply.github.com>
Date: Wed, 29 Oct 2025 18:29:01 -0700
Subject: [PATCH 5/6] Update src/System.CommandLine/Command.cs
---
src/System.CommandLine/Command.cs | 3 +++
1 file changed, 3 insertions(+)
diff --git a/src/System.CommandLine/Command.cs b/src/System.CommandLine/Command.cs
index ee96453d94..14705d7323 100644
--- a/src/System.CommandLine/Command.cs
+++ b/src/System.CommandLine/Command.cs
@@ -66,6 +66,9 @@ public IEnumerable Children
///
/// Gets all of the options for the command.
///
+ ///
+ /// This collection doesn't include options on parent commands where
public IList Options => _options ??= new (this);
internal bool HasOptions => _options?.Count > 0;
From c57eb6ddb38f5a8ab703c21f2f73e386027adee7 Mon Sep 17 00:00:00 2001
From: Genevieve Warren <24882762+gewarren@users.noreply.github.com>
Date: Thu, 30 Oct 2025 09:51:43 -0700
Subject: [PATCH 6/6] Apply suggestions from code review
---
src/System.CommandLine/Command.cs | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/src/System.CommandLine/Command.cs b/src/System.CommandLine/Command.cs
index 14705d7323..a44f9789e0 100644
--- a/src/System.CommandLine/Command.cs
+++ b/src/System.CommandLine/Command.cs
@@ -67,8 +67,8 @@ public IEnumerable Children
/// Gets all of the options for the command.
///
///
- /// This collection doesn't include options on parent commands where
+ /// This collection doesn't include options on parent commands where Option.Recursive is
public IList Options => _options ??= new (this);
internal bool HasOptions => _options?.Count > 0;