[release/10.0] Backport API docs improvements

src/System.CommandLine/Argument.cs

@@ -45,8 +45,21 @@ public ArgumentArity Arity
         }
 
         /// <summary>
-        /// The name used in help output to describe the argument. 
+        /// 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>
+        /// <remarks>
+        /// If <c>null</c>, the <see cref="Symbol.Name"/> of the argument will be 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

src/System.CommandLine/Completions/CompletionContext.cs

@@ -23,10 +23,14 @@ internal CompletionContext(ParseResult parseResult, string wordToComplete)
             WordToComplete = wordToComplete;
         }
 
+        /// <summary>
         /// The text of the word to be completed, if any.
+        /// </summary>
         public string WordToComplete { get; }
 
+        /// <summary>
         /// The parse result for which completions are being requested.
+        /// </summary>
         public ParseResult ParseResult { get; }
 
         /// <summary>

src/System.CommandLine/OptionValidation.cs

@@ -46,7 +46,7 @@ public static Option<FileSystemInfo> AcceptExistingOnly(this Option<FileSystemIn
         }
 
         /// <summary>
-        /// Configures an option to accept only values corresponding to a existing files or directories.
+        /// Configures an option to accept only values corresponding to existing files or directories.
         /// </summary>
         /// <param name="option">The option to configure.</param>
         /// <returns>The option being extended.</returns>

src/System.CommandLine/Parsing/SymbolResult.cs

@@ -91,10 +91,13 @@ public IEnumerable<ParseError> Errors
         public DirectiveResult? GetResult(Directive directive) => SymbolResultTree.GetResult(directive);
 
         /// <summary>
-        /// Finds a result for a symbol having the specified name anywhere in the parse tree.
+        /// Finds a result for a <see cref="Symbol" /> having the specified <paramref name="name" /> anywhere in the parse tree.
         /// </summary>
-        /// <param name="name">The name of the symbol for which to find a result.</param>
-        /// <returns>An argument result if the argument was matched by the parser or has a default value; otherwise, <c>null</c>.</returns>
+        /// <param name="name">The name of the <see cref="Symbol" /> for which to find a result.</param>
+        /// <returns>
+        /// A <see cref="SymbolResult" /> if the <see cref="Symbol" /> was matched by the parser or has a default value;
+        /// otherwise, <see langword="null" />.
+        /// </returns>
         public SymbolResult? GetResult(string name) => 
             SymbolResultTree.GetResult(name);