XML documentation (Argument, Option, Command) (#1181)

Author: jonsequitur

src/System.CommandLine.Tests/ApprovalTests/ApprovalTests.Config.cs renamed to src/System.CommandLine.Tests/Help/ApprovalTests.Config.cs

@@ -1,4 +1,4 @@
-the-root-command:
+the-root-command:
   Test description
 
 Usage:

src/System.CommandLine.Tests/ApprovalTests/Help/Approvals/HelpBuilderTests.Help_describes_default_values_for_complex_root_command_scenario.approved.txt renamed to src/System.CommandLine.Tests/Help/Approvals/HelpBuilderTests.Help_describes_default_values_for_complex_root_command_scenario.approved.txt

@@ -2,7 +2,6 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 using Xunit;
-using System.CommandLine.Help;
 using System.IO;
 using ApprovalTests;
 
@@ -77,10 +76,8 @@ public void Help_describes_default_values_for_complex_root_command_scenario()
             };
             command.Name = "the-root-command";
 
-            HelpBuilder helpBuilder = GetHelpBuilder(LargeMaxWidth);
-            helpBuilder.Write(command);
-            var output = _console.Out.ToString();
-            Approvals.Verify(output);
+            GetHelpBuilder(LargeMaxWidth).Write(command);
+            Approvals.Verify(_console.Out.ToString());
         }
 
     }

src/System.CommandLine.Tests/ApprovalTests/Help/HelpBuilderTests.Approval.cs renamed to src/System.CommandLine.Tests/Help/HelpBuilderTests.Approval.cs

@@ -10,7 +10,7 @@
 namespace System.CommandLine
 {
     /// <summary>
-    /// Represents a value passed to an <see cref="Option"/> or <see cref="Command"/>.
+    /// A symbol defining a value that can be passed on the command line to a <see cref="ICommand">command</see> or <see cref="IOption">option</see>.
     /// </summary>
     public class Argument : Symbol, IArgument
     {
@@ -108,7 +108,7 @@ public List<ISuggestionSource> Suggestions
         }
 
         /// <summary>
-        /// Gets or sets the <see cref="System.Type" /> that the argument will be converted to.
+        /// Gets or sets the <see cref="Type" /> that the argument token(s) will be converted to.
         /// </summary>
         public Type ArgumentType
         {
@@ -226,13 +226,16 @@ internal void AddAllowedValues(IEnumerable<string> values)
                    .Containing(textToMatch ?? "");
         }
 
+        /// <inheritdoc />
         public override string ToString() => $"{nameof(Argument)}: {Name}";
 
         /// <inheritdoc />
         IArgumentArity IArgument.Arity => Arity;
 
+        /// <inheritdoc />
         string IValueDescriptor.ValueName => Name;
 
+        /// <inheritdoc />
         Type IValueDescriptor.ValueType => ArgumentType;
     }
 }

src/System.CommandLine/Argument.cs

@@ -121,7 +121,7 @@ internal static IArgumentArity Default(Type type, Argument argument, ISymbolSet
                 return Zero;
             }
 
-            var parent = parents.FirstOrDefault();
+            var parent = parents.Count > 0 ? parents[0] : default;
 
             if (typeof(IEnumerable).IsAssignableFrom(type) &&
                 type != typeof(string))

src/System.CommandLine/ArgumentArity.cs

@@ -6,7 +6,7 @@
 namespace System.CommandLine
 {
     /// <summary>
-    /// Defines a symbol with an arity.
+    /// A symbol defining a value that can be passed on the command line to a <see cref="ICommand">command</see> or <see cref="IOption">option</see>.
     /// </summary>
     public interface IArgument : 
         ISymbol,

src/System.CommandLine/IArgument.cs

@@ -6,18 +6,17 @@ namespace System.CommandLine
     /// <summary>
     /// Defines the arity of an argument.
     /// </summary>
-    /// <remarks>The arity of an option or command's argument refers to the number of values that can be passed if that
-    /// option or command is specified. Arity is expressed with a minimum value and a maximum value.
+    /// <remarks>The arity of an argument refers to the number of values that can be passed on the command line.
     /// </remarks>
     public interface IArgumentArity
     {
         /// <summary>
-        /// Gets the minimum number of values required for the argument.
+        /// Gets the minimum number of values required for an <see cref="IArgument">argument</see>.
         /// </summary>
         int MinimumNumberOfValues { get;  }
 
         /// <summary>
-        /// Gets the maximum number of values allowed for the argument.
+        /// Gets the maximum number of values allowed for an <see cref="IArgument">argument</see>.
         /// </summary>
         int MaximumNumberOfValues { get;  }
     }

src/System.CommandLine/IArgumentArity.cs

@@ -2,15 +2,29 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 using System.Collections.Generic;
+using System.CommandLine.Parsing;
 
 namespace System.CommandLine
 {
+    /// <summary>
+    /// A symbol definining an action that can be performed.
+    /// </summary>
+    /// <remarks>This is also often called a verb.</remarks>
     public interface ICommand : IIdentifierSymbol
     {
+        /// <summary>
+        /// Gets a value indicating whether unmatched tokens contribute errors to <see cref="ParseResult.Errors"/>>.
+        /// </summary>
         bool TreatUnmatchedTokensAsErrors { get; }
 
+        /// <summary>
+        /// Gets the <see cref="IArgument">arguments</see> that can be provided to the command.
+        /// </summary>
         IReadOnlyList<IArgument> Arguments { get; }
 
+        /// <summary>
+        /// Gets the <see cref="IOption">options</see> that can be provided to the command.
+        /// </summary>
         IReadOnlyList<IOption> Options { get; }
     }
 }

src/System.CommandLine/ICommand.cs

@@ -6,20 +6,20 @@
 namespace System.CommandLine
 {
     /// <summary>
-    /// Defines a symbol with aliases.
+    /// Defines a symbol which is an identifier on the command line, such as a <see cref="ICommand">command</see> or <see cref="IOption">option</see>.
     /// </summary>
     public interface IIdentifierSymbol : ISymbol
     {
         /// <summary>
-        /// Gets the aliases for the symbol.
+        /// Gets the set of alternative strings that can be used on the command line to specify the symbol.
         /// </summary>
         IReadOnlyCollection<string> Aliases { get; }
 
         /// <summary>
         /// Determines whether the alias has already been defined.
         /// </summary>
         /// <param name="alias">The alias to search for.</param>
-        /// <returns><c>true</c> if the alias has already been defined; otherwise <c>false</c>.</returns>
+        /// <returns><see langkeyword="true">true</see> if the alias has already been defined; otherwise <see langkeyword="true">false</see>.</returns>
         bool HasAlias(string alias);
     }
 }

src/System.CommandLine/IIdentifierSymbol.cs

@@ -6,12 +6,12 @@
 namespace System.CommandLine
 {
     /// <summary>
-    /// Defines a symbol with an argument. 
+    /// A symbol defining a named parameter and a value for that parameter. 
     /// </summary>
     public interface IOption : IIdentifierSymbol, IValueDescriptor
     {
         /// <summary>
-        /// Gets the argument for the option.
+        /// Gets the <see cref="IArgument">argument</see> for the option.
         /// </summary>
         IArgument Argument { get; }
 
@@ -21,8 +21,18 @@ public interface IOption : IIdentifierSymbol, IValueDescriptor
         bool IsRequired { get; }
 
         /// <summary>
-        /// Gets a value that indicates whether multiple argument values are allowed.
+        /// Gets a value that indicates whether multiple argument tokens are allowed for each option identifier token.
         /// </summary>
+        /// <example>
+        /// If set to <see langword="true"/>, the following command line is valid for passing multiple arguments:
+        /// <code>
+        /// > --opt 1 2 3
+        /// </code>
+        /// The following is equivalent is always valid:
+        /// <code>
+        /// > --opt 1 --opt 2 --opt 3
+        /// </code>
+        /// </example>
         bool AllowMultipleArgumentsPerToken { get; }
     }
 }