...still more XML comments

Author: jonsequitur

src/System.CommandLine/Builder/CommandLineBuilderExtensions.cs

@@ -684,7 +684,6 @@ public static CommandLineBuilder UseLocalizationResources(
         /// Enables the use of a option (defaulting to the alias <c>--version</c>) which when specified in command line input will short circuit normal command handling and instead write out version information before exiting.
         /// </summary>
         /// <param name="builder">A command line builder.</param>
-        /// <param name="aliases">One or more aliases to use instead of the default to signal that version information should be displayed.</param>
         /// <returns>The same instance of <see cref="CommandLineBuilder"/>.</returns>
         public static CommandLineBuilder UseVersionOption(
             this CommandLineBuilder builder)
@@ -720,9 +719,12 @@ public static CommandLineBuilder UseVersionOption(
 
             return builder;
         }
+
+        /// <inheritdoc cref="UseVersionOption(System.CommandLine.Builder.CommandLineBuilder)"/>
+        /// <param name="aliases">One or more aliases to use instead of the default to signal that version information should be displayed.</param>
         public static CommandLineBuilder UseVersionOption(
             this CommandLineBuilder builder,
-            params string[]? aliases)
+            params string[] aliases)
         {
             var command = builder.Command;
 

src/System.CommandLine/CommandLineConfiguration.cs

@@ -26,6 +26,7 @@ public class CommandLineConfiguration
         /// <param name="symbols">The symbols to parse.</param>
         /// <param name="enablePosixBundling"><see langword="true"/> to enable POSIX bundling; otherwise, <see langword="false"/>.</param>
         /// <param name="enableDirectives"><see langword="true"/> to enable directive parsing; otherwise, <see langword="false"/>.</param>
+        /// <param name="enableLegacyDoubleDashBehavior">Enables the legacy behavior of the <c>--</c> token, which is to ignore parsing of subsequent tokens and place them in the <see cref="ParseResult.UnparsedTokens"/> list.</param>
         /// <param name="resources">Provide custom validation messages.</param>
         /// <param name="responseFileHandling">One of the enumeration values that specifies how response files (.rsp) are handled.</param>
         /// <param name="middlewarePipeline">Provide a custom middleware pipeline.</param>
@@ -37,6 +38,7 @@ public CommandLineConfiguration(
             IReadOnlyList<Symbol> symbols,
             bool enablePosixBundling = true,
             bool enableDirectives = true,
+            bool enableLegacyDoubleDashBehavior = false,
             Resources? resources = null,
             ResponseFileHandling responseFileHandling = ResponseFileHandling.ParseArgsAsLineSeparated,
             IReadOnlyCollection<InvocationMiddleware>? middlewarePipeline = null,
@@ -84,6 +86,7 @@ public CommandLineConfiguration(
 
             AddGlobalOptionsToChildren(rootCommand);
 
+            EnableLegacyDoubleDashBehavior = enableLegacyDoubleDashBehavior;
             EnablePosixBundling = enablePosixBundling;
             EnableDirectives = enableDirectives;
             Resources = resources ?? Resources.Instance;
@@ -145,6 +148,11 @@ private void AddGlobalOptionsToChildren(Command parentCommand)
         /// </summary>
         public bool EnableDirectives { get; }
 
+        /// <summary>
+        /// Enables the legacy behavior of the <c>--</c> token, which is to ignore parsing of subsequent tokens and place them in the <see cref="ParseResult.UnparsedTokens"/> list.
+        /// </summary>
+        public bool EnableLegacyDoubleDashBehavior { get; }
+
         /// <summary>
         /// Gets whether POSIX bundling is enabled.
         /// </summary>

src/System.CommandLine/Invocation/CommandHandler.NameBasedBinding.cs

@@ -484,152 +484,152 @@ public static ICommandHandler Create<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T1
             HandlerDescriptor.FromDelegate(action).GetCommandHandler();
 
         /// <summary>
-        /// Creates a command handler based on a <see cref="Func{Task{Int32}}"/>.
+        /// Creates a command handler based on a <see cref="Func{Task}"/>.
         /// </summary>
-        /// <param name="action">The <see cref="Func{Task{Int32}}"/> to be called when the command handler is invoked.</param>
+        /// <param name="action">The <see cref="Func{Task}"/> to be called when the command handler is invoked.</param>
         /// <returns>An instance of <see cref="ICommandHandler"/>.</returns>
         public static ICommandHandler Create(Func<Task<int>> action) =>
             HandlerDescriptor.FromDelegate(action).GetCommandHandler();
 
         /// <summary>
-        /// Creates a command handler based on a <see cref="Func{T,Task{Int32}}"/>.
+        /// Creates a command handler based on a <see cref="Func{T,Task}"/>.
         /// </summary>
-        /// <param name="action">The <see cref="Func{T,Task{Int32}}"/> to be called when the command handler is invoked.</param>
+        /// <param name="action">The <see cref="Func{T,Task}"/> to be called when the command handler is invoked.</param>
         /// <returns>An instance of <see cref="ICommandHandler"/>.</returns>
         public static ICommandHandler Create<T>(
             Func<T, Task<int>> action) =>
             HandlerDescriptor.FromDelegate(action).GetCommandHandler();
 
         /// <summary>
-        /// Creates a command handler based on a <see cref="Func{T1,T2,Task{Int32}}"/>.
+        /// Creates a command handler based on a <see cref="Func{T1,T2,Task}"/>.
         /// </summary>
-        /// <param name="action">The <see cref="Func{T1,T2,Task{Int32}}"/> to be called when the command handler is invoked.</param>
+        /// <param name="action">The <see cref="Func{T1,T2,Task}"/> to be called when the command handler is invoked.</param>
         /// <returns>An instance of <see cref="ICommandHandler"/>.</returns>
         public static ICommandHandler Create<T1, T2>(
             Func<T1, T2, Task<int>> action) =>
             HandlerDescriptor.FromDelegate(action).GetCommandHandler();
 
         /// <summary>
-        /// Creates a command handler based on a <see cref="Func{T1,T2,T3,Task{Int32}}"/>.
+        /// Creates a command handler based on a <see cref="Func{T1,T2,T3,Task}"/>.
         /// </summary>
-        /// <param name="action">The <see cref="Func{T1,T2,T3,Task{Int32}}"/> to be called when the command handler is invoked.</param>
+        /// <param name="action">The <see cref="Func{T1,T2,T3,Task}"/> to be called when the command handler is invoked.</param>
         /// <returns>An instance of <see cref="ICommandHandler"/>.</returns>
         public static ICommandHandler Create<T1, T2, T3>(
             Func<T1, T2, T3, Task<int>> action) =>
             HandlerDescriptor.FromDelegate(action).GetCommandHandler();
 
         /// <summary>
-        /// Creates a command handler based on a <see cref="Func{T1,T2,T3,T4,Task{Int32}}"/>.
+        /// Creates a command handler based on a <see cref="Func{T1,T2,T3,T4,Task}"/>.
         /// </summary>
-        /// <param name="action">The <see cref="Func{T1,T2,T3,T4,Task{Int32}}"/> to be called when the command handler is invoked.</param>
+        /// <param name="action">The <see cref="Func{T1,T2,T3,T4,Task}"/> to be called when the command handler is invoked.</param>
         /// <returns>An instance of <see cref="ICommandHandler"/>.</returns>
         public static ICommandHandler Create<T1, T2, T3, T4>(
             Func<T1, T2, T3, T4, Task<int>> action) =>
             HandlerDescriptor.FromDelegate(action).GetCommandHandler();
 
         /// <summary>
-        /// Creates a command handler based on a <see cref="Func{T1,T2,T3,T4,T5,Task{Int32}}"/>.
+        /// Creates a command handler based on a <see cref="Func{T1,T2,T3,T4,T5,Task}"/>.
         /// </summary>
-        /// <param name="action">The <see cref="Func{T1,T2,T3,T4,T5,Task{Int32}}"/> to be called when the command handler is invoked.</param>
+        /// <param name="action">The <see cref="Func{T1,T2,T3,T4,T5,Task}"/> to be called when the command handler is invoked.</param>
         /// <returns>An instance of <see cref="ICommandHandler"/>.</returns>
         public static ICommandHandler Create<T1, T2, T3, T4, T5>(
             Func<T1, T2, T3, T4, T5, Task<int>> action) =>
             HandlerDescriptor.FromDelegate(action).GetCommandHandler();
 
         /// <summary>
-        /// Creates a command handler based on a <see cref="Func{T1,T2,T3,T4,T5,T6,Task{Int32}}"/>.
+        /// Creates a command handler based on a <see cref="Func{T1,T2,T3,T4,T5,T6,Task}"/>.
         /// </summary>
-        /// <param name="action">The <see cref="Func{T1,T2,T3,T4,T5,T6,Task{Int32}}"/> to be called when the command handler is invoked.</param>
+        /// <param name="action">The <see cref="Func{T1,T2,T3,T4,T5,T6,Task}"/> to be called when the command handler is invoked.</param>
         /// <returns>An instance of <see cref="ICommandHandler"/>.</returns>
         public static ICommandHandler Create<T1, T2, T3, T4, T5, T6>(
             Func<T1, T2, T3, T4, T5, T6, Task<int>> action) =>
             HandlerDescriptor.FromDelegate(action).GetCommandHandler();
 
         /// <summary>
-        /// Creates a command handler based on a <see cref="Func{T1,T2,T3,T4,T5,T6,T7,Task{Int32}}"/>.
+        /// Creates a command handler based on a <see cref="Func{T1,T2,T3,T4,T5,T6,T7,Task}"/>.
         /// </summary>
-        /// <param name="action">The <see cref="Func{T1,T2,T3,T4,T5,T6,T7,Task{Int32}}"/> to be called when the command handler is invoked.</param>
+        /// <param name="action">The <see cref="Func{T1,T2,T3,T4,T5,T6,T7,Task}"/> to be called when the command handler is invoked.</param>
         /// <returns>An instance of <see cref="ICommandHandler"/>.</returns>
         public static ICommandHandler Create<T1, T2, T3, T4, T5, T6, T7>(
             Func<T1, T2, T3, T4, T5, T6, T7, Task<int>> action) =>
             HandlerDescriptor.FromDelegate(action).GetCommandHandler();
 
         /// <summary>
-        /// Creates a command handler based on a <see cref="Func{T1,T2,T3,T4,T5,T6,T7,T8,Task{Int32}}"/>.
+        /// Creates a command handler based on a <see cref="Func{T1,T2,T3,T4,T5,T6,T7,T8,Task}"/>.
         /// </summary>
-        /// <param name="action">The <see cref="Func{T1,T2,T3,T4,T5,T6,T7,T8,Task{Int32}}"/> to be called when the command handler is invoked.</param>
+        /// <param name="action">The <see cref="Func{T1,T2,T3,T4,T5,T6,T7,T8,Task}"/> to be called when the command handler is invoked.</param>
         /// <returns>An instance of <see cref="ICommandHandler"/>.</returns>
         public static ICommandHandler Create<T1, T2, T3, T4, T5, T6, T7, T8>(
             Func<T1, T2, T3, T4, T5, T6, T7, T8, Task<int>> action) =>
             HandlerDescriptor.FromDelegate(action).GetCommandHandler();
 
         /// <summary>
-        /// Creates a command handler based on a <see cref="Func{T1,T2,T3,T4,T5,T6,T7,T8,T9,Task{Int32}}"/>.
+        /// Creates a command handler based on a <see cref="Func{T1,T2,T3,T4,T5,T6,T7,T8,T9,Task}"/>.
         /// </summary>
-        /// <param name="action">The <see cref="Func{T1,T2,T3,T4,T5,T6,T7,T8,T9,Task{Int32}}"/> to be called when the command handler is invoked.</param>
+        /// <param name="action">The <see cref="Func{T1,T2,T3,T4,T5,T6,T7,T8,T9,Task}"/> to be called when the command handler is invoked.</param>
         /// <returns>An instance of <see cref="ICommandHandler"/>.</returns>
         public static ICommandHandler Create<T1, T2, T3, T4, T5, T6, T7, T8, T9>(
             Func<T1, T2, T3, T4, T5, T6, T7, T8, T9, Task<int>> action) =>
             HandlerDescriptor.FromDelegate(action).GetCommandHandler();
 
         /// <summary>
-        /// Creates a command handler based on a <see cref="Func{T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,Task{Int32}}"/>.
+        /// Creates a command handler based on a <see cref="Func{T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,Task}"/>.
         /// </summary>
-        /// <param name="action">The <see cref="Func{T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,Task{Int32}}"/> to be called when the command handler is invoked.</param>
+        /// <param name="action">The <see cref="Func{T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,Task}"/> to be called when the command handler is invoked.</param>
         /// <returns>An instance of <see cref="ICommandHandler"/>.</returns>
         public static ICommandHandler Create<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10>(
             Func<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, Task<int>> action) =>
             HandlerDescriptor.FromDelegate(action).GetCommandHandler();
 
         /// <summary>
-        /// Creates a command handler based on a <see cref="Func{T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,Task{Int32}}"/>.
+        /// Creates a command handler based on a <see cref="Func{T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,Task}"/>.
         /// </summary>
-        /// <param name="action">The <see cref="Func{T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,Task{Int32}}"/> to be called when the command handler is invoked.</param>
+        /// <param name="action">The <see cref="Func{T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,Task}"/> to be called when the command handler is invoked.</param>
         /// <returns>An instance of <see cref="ICommandHandler"/>.</returns>
         public static ICommandHandler Create<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11>(
             Func<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, Task<int>> action) =>
             HandlerDescriptor.FromDelegate(action).GetCommandHandler();
 
         /// <summary>
-        /// Creates a command handler based on a <see cref="Func{T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,Task{Int32}}"/>.
+        /// Creates a command handler based on a <see cref="Func{T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,Task}"/>.
         /// </summary>
-        /// <param name="action">The <see cref="Func{T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,Task{Int32}}"/> to be called when the command handler is invoked.</param>
+        /// <param name="action">The <see cref="Func{T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,Task}"/> to be called when the command handler is invoked.</param>
         /// <returns>An instance of <see cref="ICommandHandler"/>.</returns>
         public static ICommandHandler Create<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12>(
             Func<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, Task<int>> action) =>
             HandlerDescriptor.FromDelegate(action).GetCommandHandler();
 
         /// <summary>
-        /// Creates a command handler based on a <see cref="Func{T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,Task{Int32}}"/>.
+        /// Creates a command handler based on a <see cref="Func{T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,Task}"/>.
         /// </summary>
-        /// <param name="action">The <see cref="Func{T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,Task{Int32}}"/> to be called when the command handler is invoked.</param>
+        /// <param name="action">The <see cref="Func{T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,Task}"/> to be called when the command handler is invoked.</param>
         /// <returns>An instance of <see cref="ICommandHandler"/>.</returns>
         public static ICommandHandler Create<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13>(
             Func<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, Task<int>> action) =>
             HandlerDescriptor.FromDelegate(action).GetCommandHandler();
 
         /// <summary>
-        /// Creates a command handler based on a <see cref="Func{T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,T14,Task{Int32}}"/>.
+        /// Creates a command handler based on a <see cref="Func{T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,T14,Task}"/>.
         /// </summary>
-        /// <param name="action">The <see cref="Func{T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,T14,Task{Int32}}"/> to be called when the command handler is invoked.</param>
+        /// <param name="action">The <see cref="Func{T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,T14,Task}"/> to be called when the command handler is invoked.</param>
         /// <returns>An instance of <see cref="ICommandHandler"/>.</returns>
         public static ICommandHandler Create<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14>(
             Func<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14, Task<int>> action) =>
             HandlerDescriptor.FromDelegate(action).GetCommandHandler();
 
         /// <summary>
-        /// Creates a command handler based on a <see cref="Func{T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,T14,T15,Task{Int32}}"/>.
+        /// Creates a command handler based on a <see cref="Func{T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,T14,T15,Task}"/>.
         /// </summary>
-        /// <param name="action">The <see cref="Func{T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,T14,T15,Task{Int32}}"/> to be called when the command handler is invoked.</param>
+        /// <param name="action">The <see cref="Func{T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,T14,T15,Task}"/> to be called when the command handler is invoked.</param>
         /// <returns>An instance of <see cref="ICommandHandler"/>.</returns>
         public static ICommandHandler Create<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14, T15>(
             Func<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14, T15, Task<int>> action) =>
             HandlerDescriptor.FromDelegate(action).GetCommandHandler();
 
         /// <summary>
-        /// Creates a command handler based on a <see cref="Func{T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,T14,T15,T16,Task{Int32}}"/>.
+        /// Creates a command handler based on a <see cref="Func{T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,T14,T15,T16,Task}"/>.
         /// </summary>
-        /// <param name="action">The <see cref="Func{T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,T14,T15,T16,Task{Int32}}"/> to be called when the command handler is invoked.</param>
+        /// <param name="action">The <see cref="Func{T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,T14,T15,T16,Task}"/> to be called when the command handler is invoked.</param>
         /// <returns>An instance of <see cref="ICommandHandler"/>.</returns>
         public static ICommandHandler Create<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14, T15, T16>(
             Func<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14, T15, T16, Task<int>> action) =>