Apply comments from #7859 (#1701)

* Apply comments from #7859

* Update src/System.CommandLine/Parsing/Parser.cs

Co-authored-by: Genevieve Warren <[email protected]>

* add builder param

Co-authored-by: Genevieve Warren <[email protected]>

Author: tdykstra

src/System.CommandLine/Builder/CommandLineBuilderExtensions.cs

@@ -100,8 +100,9 @@ public static CommandLineBuilder CancelOnProcessTermination(this CommandLineBuil
         /// Enables the parser to recognize command line directives.
         /// </summary>
         /// <param name="builder">A command line builder.</param>
-        /// <param name="value">If set to <see langword="true"/>, then directives are enabled. Otherwise, they are parsed like any other token.</param>
+        /// <param name="value"><see langword="true" /> to enable directives. <see langword="false" /> to parse directive-like tokens in the same way as any other token.</param>
         /// <returns>The same instance of <see cref="CommandLineBuilder"/>.</returns>
+        /// <seealso href="/dotnet/standard/commandline/syntax#directives">Command-line directives</seealso> 
         /// <seealso cref="DirectiveCollection"/>
         public static CommandLineBuilder EnableDirectives(
             this CommandLineBuilder builder,
@@ -114,7 +115,8 @@ public static CommandLineBuilder EnableDirectives(
         /// <summary>
         /// Determines the behavior when parsing a double dash (<c>--</c>) in a command line.
         /// </summary>
-        /// <remarks>When set to <see langword="true"/>, all tokens following <c>--</c> will be placed into the <see cref="ParseResult.UnparsedTokens"/> collection. When set to <see langword="false"/>, all tokens following <c>--</c> will be treated as command arguments, even if they match an existing option.</remarks>
+        /// <param name="builder">A command line builder.</param>
+        /// <param name="value"><see langword="true" /> to place all tokens following <c>--</c> into the <see cref="ParseResult.UnparsedTokens"/> collection. <see langword="false" /> to treat all tokens following <c>--</c> as command arguments, even if they match an existing option.</param>
         public static CommandLineBuilder EnableLegacyDoubleDashBehavior(
             this CommandLineBuilder builder,
             bool value = true)
@@ -127,7 +129,7 @@ public static CommandLineBuilder EnableLegacyDoubleDashBehavior(
         /// Enables the parser to recognize and expand POSIX-style bundled options.
         /// </summary>
         /// <param name="builder">A command line builder.</param>
-        /// <param name="value">If set to <see langword="true"/>, then POSIX bundles are parsed. ; otherwise, <see langword="false"/>.</param>
+        /// <param name="value"><see langword="true"/> to parse POSIX bundles; otherwise, <see langword="false"/>.</param>
         /// <returns>The same instance of <see cref="CommandLineBuilder"/>.</returns>
         /// <remarks>
         /// POSIX conventions recommend that single-character options be allowed to be specified together after a single <c>-</c> prefix. When <see cref="EnablePosixBundling"/> is set to <see langword="true"/>, the following command lines are equivalent:

src/System.CommandLine/IdentifierSymbol.cs

@@ -60,9 +60,12 @@ public override string Name
         }
 
         /// <summary>
-        /// Adds an alias. Multiple aliases can be added, most often used to provide a shorthand alternative.
+        /// Adds an <see href="/dotnet/standard/commandline/syntax#aliases">alias</see>.
         /// </summary>
         /// <param name="alias">The alias to add.</param>
+        /// <remarks>
+        /// You can add multiple aliases for a symbol.
+        /// </remarks>
         public void AddAlias(string alias)
         {
             ThrowIfAliasIsInvalid(alias);
@@ -73,10 +76,10 @@ public void AddAlias(string alias)
         private protected virtual void RemoveAlias(string alias) => _aliases.Remove(alias);
 
         /// <summary>
-        /// Determines whether the alias has already been defined.
+        /// Determines whether the specified alias has already been defined.
         /// </summary>
         /// <param name="alias">The alias to search for.</param>
-        /// <returns><see langword="true">true</see> if the alias has already been defined; otherwise <see langkeyword="true">false</see>.</returns>
+        /// <returns><see langword="true" /> if the alias has already been defined; otherwise <see langword="false" />.</returns>
         public bool HasAlias(string alias) => _aliases.Contains(alias);
 
         [DebuggerStepThrough]

src/System.CommandLine/Parsing/Parser.cs

@@ -23,22 +23,22 @@ public Parser(Command command) : this(new CommandLineConfiguration(command))
         }
 
         /// <summary>
-        /// Initializes a new instance of the Parser class with using the default <seealso cref="RootCommand"/>.
+        /// Initializes a new instance of the <see cref="Parser" /> class using the default <see cref="RootCommand" />.
         /// </summary>
         public Parser() : this(new RootCommand())
         {
         }
 
         /// <summary>
-        /// The configuration on which the parser's grammar and behaviors are based.
+        /// Gets the configuration on which the parser's grammar and behaviors are based.
         /// </summary>
         public CommandLineConfiguration Configuration { get; }
 
         /// <summary>
         /// Parses a list of arguments.
         /// </summary>
         /// <param name="arguments">The string array typically passed to a program's <c>Main</c> method.</param>
-        /// <param name="rawInput">Holds the value of a complete command line input prior to splitting and tokenization, when provided. This will typically not be available when the parser is called from <c>Program.Main</c>. It is primarily used when calculating completions via the <c>dotnet-suggest</c> tool.</param>
+        /// <param name="rawInput">The complete command line input prior to splitting and tokenization. This input is not typically available when the parser is called from <c>Program.Main</c>. It is primarily used when calculating completions via the <c>dotnet-suggest</c> tool.</param>
         /// <returns>A <see cref="ParseResult"/> providing details about the parse operation.</returns>
         public ParseResult Parse(
             IReadOnlyList<string> arguments,