Docs improvements (#2709)

Author: gewarren

src/System.CommandLine/Argument.cs

@@ -10,7 +10,7 @@
 namespace System.CommandLine
 {
     /// <summary>
-    /// A symbol defining a value that can be passed on the command line to a <see cref="Command">command</see> or <see cref="Option">option</see>.
+    /// Represents a symbol that defines a value that can be passed on the command line to a <see cref="Command">command</see> or <see cref="Option">option</see>.
     /// </summary>
     public abstract class Argument : Symbol
     {
@@ -22,7 +22,7 @@ public abstract class Argument : Symbol
         /// <summary>
         /// Initializes a new instance of the Argument class.
         /// </summary>
-        /// <param name="name">The name of the argument. This can be used to look up the parsed value and is displayed in help</param>
+        /// <param name="name">The name of the argument. This value can be used to look up the parsed value and is displayed in help if <see cref="HelpName" /> is null.</param>
         protected Argument(string name) : base(name, allowWhitespace: true)
         {
         }
@@ -48,18 +48,18 @@ 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 (<c>&lt;</c> and <c>&gt;</c>).
         /// </summary>
+        /// <value>
+        /// The name to show as the placeholder for the argument's value.
+        /// </value>
         /// <remarks>
-        /// If <c>null</c>, the <see cref="Symbol.Name"/> of the argument will be used.
+        /// If <c>null</c>, the <see cref="Symbol.Name"/> of the argument is used.
         /// </remarks>
         /// <example>
         /// An argument with <see cref="Symbol.Name"/> of <c>argument</c> and a
         /// <see cref="HelpName"/> of <c>Value</c> will be shown in usage help as:
         /// <c>&lt;Value&gt;</c>. If <see cref="HelpName"/> is not set,
         /// help output will show: <c>&lt;argument&gt;</c>.
         /// </example>
-        /// <value>
-        /// The name to show as the placeholder for the argument's value.
-        /// </value>
         public string? HelpName { get; set; }
 
         internal TryConvertArgument? ConvertArguments
@@ -107,12 +107,12 @@ public List<Func<CompletionContext, IEnumerable<CompletionItem>>> CompletionSour
         }
 
         /// <summary>
-        /// Gets or sets the <see cref="Type" /> that the argument's parsed tokens will be converted to.
+        /// Gets the type that the argument's parsed tokens will be converted to.
         /// </summary>
         public abstract Type ValueType { get; }
 
         /// <summary>
-        /// 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.
         /// </summary>
         public List<Action<ArgumentResult>> Validators => _validators ??= new ();
@@ -122,7 +122,7 @@ public List<Func<CompletionContext, IEnumerable<CompletionItem>>> CompletionSour
         /// <summary>
         /// Gets the default value for the argument.
         /// </summary>
-        /// <returns>Returns the default value for the argument, if defined. Null otherwise.</returns>
+        /// <returns>The default value for the argument, if defined; otherwise, <see langword="null" />.</returns>
         public object? GetDefaultValue()
         {
             var command = Parents.FlattenBreadthFirst(x => x.Parents)
@@ -135,7 +135,7 @@ public List<Func<CompletionContext, IEnumerable<CompletionItem>>> CompletionSour
         internal abstract object? GetDefaultValue(ArgumentResult argumentResult);
 
         /// <summary>
-        /// Specifies if a default value is defined for the argument.
+        /// Gets a value that indicates if a default value is defined for the argument.
         /// </summary>
         public abstract bool HasDefaultValue { get; }
 

src/System.CommandLine/Argument{T}.cs

@@ -15,17 +15,17 @@ public class Argument<T> : Argument
         /// <summary>
         /// Initializes a new instance of the Argument class.
         /// </summary>
-        /// <param name="name">The name of the argument. This can be used to look up the parsed value and is displayed in help</param>
+        /// <param name="name">The name of the argument. This name can be used to look up the parsed value and is displayed in help.</param>
         public Argument(string name) : base(name)
         {
         }
 
         /// <summary>
-        /// The delegate to invoke to create the default value.
+        /// Gets or sets the delegate to invoke to create the default value.
         /// </summary>
         /// <remarks>
-        /// It's invoked when there was no parse input provided for given Argument.
-        /// The same instance can be set as <see cref="CustomParser"/>, in such case
+        /// This delegate is invoked when there was no parse input provided for given Argument.
+        /// The same instance can be set as <see cref="CustomParser"/>. In that case,
         /// the delegate is also invoked when an input was provided.
         /// </remarks>
         public Func<ArgumentResult, T>? DefaultValueFactory
@@ -45,11 +45,11 @@ public Func<ArgumentResult, T>? DefaultValueFactory
         }
 
         /// <summary>
-        /// A custom argument parser.
+        /// Gets or sets a custom argument parser.
         /// </summary>
         /// <remarks>
-        /// It's invoked when there was parse input provided for given Argument.
-        /// The same instance can be set as <see cref="DefaultValueFactory"/>, 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 <see cref="DefaultValueFactory"/>; in that case,
         /// the delegate is also invoked when no input was provided.
         /// </remarks>
         public Func<ArgumentResult, T?>? CustomParser

src/System.CommandLine/Command.cs

@@ -18,9 +18,9 @@ namespace System.CommandLine
     /// Represents a specific action that the application performs.
     /// </summary>
     /// <remarks>
-    /// Use the Command object for actions that correspond to a specific string (the command name). See
-    /// <see cref="RootCommand"/> for simple applications that only have one action. For example, <c>dotnet run</c>
-    /// uses <c>run</c> 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 <see cref="RootCommand"/>.
+    /// For example, <c>dotnet run</c> uses <c>run</c> as the command.
     /// </remarks>
     public class Command : Symbol, IEnumerable
     {
@@ -57,28 +57,31 @@ public IEnumerable<Symbol> Children
         }
 
         /// <summary>
-        /// Represents all of the arguments for the command.
+        /// Gets all of the arguments for the command.
         /// </summary>
         public IList<Argument> Arguments => _arguments ??= new(this);
 
         internal bool HasArguments => _arguments?.Count > 0 ;
 
         /// <summary>
-        /// 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.
         /// </summary>
+        /// <remarks>
+        /// This collection doesn't include options on parent commands where <see cref="Option.Recursive">Option.Recursive</see> is <see langword="true" />. Those options are valid under the current command but don't appear in this collection.
+        /// </remarks>
         public IList<Option> Options => _options ??= new (this);
 
         internal bool HasOptions => _options?.Count > 0;
 
         /// <summary>
-        /// Represents all of the subcommands for the command.
+        /// Gets all of the subcommands for the command.
         /// </summary>
         public IList<Command> Subcommands => _subcommands ??= new(this);
 
         internal bool HasSubcommands => _subcommands is not null && _subcommands.Count > 0;
 
         /// <summary>
-        /// Validators to the command. Validators can be used
+        /// Gets the validators to the command. Validators can be used
         /// to create custom validation logic.
         /// </summary>
         public List<Action<CommandResult>> Validators => _validators ??= new ();
@@ -215,9 +218,9 @@ public void SetAction(Func<ParseResult, CancellationToken, Task<int>> action)
         /// </summary>
         /// <param name="argument">The option to add to the command.</param>
         public void Add(Argument argument) =>  Arguments.Add(argument);
-        
+
         /// <summary>
-        /// Adds a <see cref="Option"/> to the command.
+        /// Adds an <see cref="Option"/> to the command.
         /// </summary>
         /// <param name="option">The option to add to the command.</param>
         public void Add(Option option) =>  Options.Add(option);
@@ -226,17 +229,17 @@ public void SetAction(Func<ParseResult, CancellationToken, Task<int>> action)
         /// Adds a <see cref="Command"/> to the command.
         /// </summary>
         /// <param name="command">The Command to add to the command.</param>
-        public void Add(Command command) =>  Subcommands.Add(command);
+        public void Add(Command command) => Subcommands.Add(command);
 
         /// <summary>
-        /// Gets or sets a value that indicates whether unmatched tokens should be treated as errors. For example,
-        /// if set to <see langword="true"/> 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.
         /// </summary>
+        /// <value><see langword="true"/> to fail validation when an extra command or argument is provided; otherwise, <see langword="false"/>.</value>
         public bool TreatUnmatchedTokensAsErrors { get; set; } = true;
 
         /// <inheritdoc />
         [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();
 
         /// <summary>

src/System.CommandLine/Completions/SuggestDirective.cs

@@ -3,7 +3,7 @@
 namespace System.CommandLine.Completions;
 
 /// <summary>
-/// Enables the use of the <c>[suggest]</c> 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 <c>[suggest]</c> 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.
 /// </summary>
 /// <remarks>The <c>dotnet-suggest</c> tool requires the suggest directive to be enabled for an application to provide completions.</remarks>
 public sealed class SuggestDirective : Directive
@@ -22,4 +22,4 @@ public override CommandLineAction? Action
         set => _action = value ?? throw new ArgumentNullException(nameof(value));
     }
 
-}
+}

src/System.CommandLine/Directive.cs

@@ -8,14 +8,16 @@
 namespace System.CommandLine
 {
     /// <summary>
-    /// 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.
+    /// </summary>
+    /// <remarks>
     /// 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.
-    /// </summary>
+    /// </remarks>
     public class Directive : Symbol
     {
         /// <summary>

src/System.CommandLine/Help/HelpAction.cs

@@ -3,19 +3,19 @@
 namespace System.CommandLine.Help
 {
     /// <summary>
-    /// Provides command line help.
+    /// Provides command-line help.
     /// </summary>
     public sealed class HelpAction : SynchronousCommandLineAction
     {
         private HelpBuilder? _builder;
         private int _maxWidth = -1;
 
         /// <summary>
-        /// 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.
         /// </summary>
-        /// <remarks>It defaults to <see cref="Console.WindowWidth"/>.</remarks>
+        /// <value>The maximum width in characters after which help output is wrapped. The default is <see cref="Console.WindowWidth"/>.</value>
         public int MaxWidth
-        { 
+        {
             get
             {
                 if (_maxWidth < 0)
@@ -44,7 +44,7 @@ public int MaxWidth
         }
 
         /// <summary>
-        /// Specifies an <see cref="Builder"/> to be used to format help output when help is requested.
+        /// Gets or sets the <see cref="Builder"/> to use to format help output.
         /// </summary>
         internal HelpBuilder Builder
         {
@@ -68,4 +68,4 @@ public override int Invoke(ParseResult parseResult)
 
         public override bool ClearsParseErrors => true;
     }
-}
+}

src/System.CommandLine/Invocation/ParseErrorAction.cs

@@ -10,20 +10,20 @@
 namespace System.CommandLine.Invocation;
 
 /// <summary>
-/// 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.
 /// </summary>
 public sealed class ParseErrorAction : SynchronousCommandLineAction
 {
     /// <summary>
-    /// 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.
     /// </summary>
-    /// <remarks>When set to <see langword="true" />, indicates that help will be shown along with parse error details. When set to false, help will not be shown.</remarks>
+    /// <value><see langword="true" /> to show help along with parse error details. <see langword="false" /> to not show help.</value>
     public bool ShowHelp { get; set; } = true;
 
     /// <summary>
-    /// 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.
     /// </summary>
-    /// <remarks>When set to <see langword="true" />, indicates that suggestions will be shown along with parse error details. When set to false, suggestions will not be shown.</remarks>
+    /// <value><see langword="true" /> to show suggestions along with parse error details. <see langword="false" /> to now show suggestions.</value>
     public bool ShowTypoCorrections { get; set; } = true;
 
     /// <inheritdoc />
@@ -232,4 +232,4 @@ static int GetDistance(string first, string second)
     }
 
     private const int MaxLevenshteinDistance = 3;
-}
+}

src/System.CommandLine/InvocationConfiguration.cs

@@ -9,37 +9,46 @@ public class InvocationConfiguration
     private TextWriter? _output, _error;
 
     /// <summary>
-    /// 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.
     /// </summary>
+    /// <value><see langword="true"/> if a default exception handler catches any unhandled exceptions thrown during invocation. The default is <see langword="true"/>.</value>
     public bool EnableDefaultExceptionHandler { get; set; } = true;
 
     /// <summary>
-    /// Enables signaling and handling of process termination (Ctrl+C, SIGINT, SIGTERM) via a <see cref="CancellationToken"/> 
+    /// Gets or sets a time span that enables signaling and handling of process termination (Ctrl+C, SIGINT, SIGTERM) via a <see cref="CancellationToken"/>
     /// that can be passed to a <see cref="CommandLineAction"/> during invocation.
-    /// If not provided, a default timeout of 2 seconds is enforced.
     /// </summary>
-    public TimeSpan? ProcessTerminationTimeout { get; set; } = TimeSpan.FromSeconds(2); 
+    /// <value>The default is two seconds.</value>
+    /// <remarks>
+    /// If this property is set to <see langword="null" />, 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.
+    /// </remarks>
+    public TimeSpan? ProcessTerminationTimeout { get; set; } = TimeSpan.FromSeconds(2);
 
     /// <summary>
-    /// The standard output. Used by Help and other facilities that write non-error information.
-    /// By default it's set to <see cref="Console.Out"/>.
-    /// For testing purposes, it can be set to a new instance of <see cref="StringWriter"/>.
-    /// If you want to disable the output, please set it to <see cref="TextWriter.Null"/>.
+    /// Gets or sets the standard output.
     /// </summary>
+    /// <value>The default is set to <see cref="Console.Out"/>.</value>
+    /// <remarks>
+    /// 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 <see cref="StringWriter"/>.
+    /// If you want to disable the output, set it to <see cref="TextWriter.Null"/>.
+    /// </remarks>
     public TextWriter Output
     {
         get => _output ??= Console.Out;
         set => _output = value ?? throw new ArgumentNullException(nameof(value), "Use TextWriter.Null to disable the output");
     }
 
     /// <summary>
-    /// The standard error. Used for printing error information like parse errors.
-    /// By default it's set to <see cref="Console.Error"/>.
-    /// For testing purposes, it can be set to a new instance of <see cref="StringWriter"/>.
+    /// Gets or sets the standard error used for printing error information like parse errors.
     /// </summary>
+    /// <value>The default is set to <see cref="Console.Error"/>.</value>
+    /// <remarks>
+    /// For testing purposes, it can be set to a new instance of <see cref="StringWriter"/>.
+    /// </remarks>
     public TextWriter Error
     {
         get => _error ??= Console.Error;
         set => _error = value ?? throw new ArgumentNullException(nameof(value), "Use TextWriter.Null to disable the output");
     }
-}
+}