Skip to content

Conversation

@v-alje
Copy link
Contributor

@v-alje v-alje commented Mar 22, 2022

Summary

This pull request adds the CommandLine API reference for the System.CommandLine NuGet package.

@v-alje v-alje requested a review from a team as a code owner March 22, 2022 23:30
@ghost
Copy link

ghost commented Mar 22, 2022

I couldn't figure out the best area label to add to this PR. If you have write-permissions please help me learn by adding exactly one area label.

@opbld31
Copy link

opbld31 commented Mar 22, 2022

Docs Build status updates of commit 0e6af4f:

✅ Validation status: passed

File Status Preview URL Details
xml/System.CommandLine.Binding/BoundValue.xml 💡Suggestion View Details
xml/System.CommandLine.Builder/CommandLineBuilderExtensions.xml 💡Suggestion View Details
xml/System.CommandLine.Parsing/Parser.xml 💡Suggestion View Details
xml/System.CommandLine.Parsing/ResponseFileHandling.xml 💡Suggestion View Details
xml/System.CommandLine.Parsing/Token.xml 💡Suggestion View Details
xml/System.CommandLine/ArgumentArity.xml 💡Suggestion View Details
xml/System.CommandLine/IdentifierSymbol.xml 💡Suggestion View Details
xml/System.CommandLine/Option`1.xml 💡Suggestion View Details
xml/FrameworksIndex/system-commandline.xml ✅Succeeded
xml/System.CommandLine.Binding/BinderBase`1.xml ✅Succeeded View
xml/System.CommandLine.Binding/BindingContext.xml ✅Succeeded View
xml/System.CommandLine.Binding/IValueDescriptor.xml ✅Succeeded View
xml/System.CommandLine.Binding/IValueDescriptor`1.xml ✅Succeeded View
xml/System.CommandLine.Binding/IValueSource.xml ✅Succeeded View
xml/System.CommandLine.Builder/CommandLineBuilder.xml ✅Succeeded View
xml/System.CommandLine.Completions/CompletionContext.xml ✅Succeeded View
xml/System.CommandLine.Completions/CompletionDelegate.xml ✅Succeeded View
xml/System.CommandLine.Completions/CompletionItem.xml ✅Succeeded View
xml/System.CommandLine.Completions/ICompletionSource.xml ✅Succeeded View
xml/System.CommandLine.Completions/TextCompletionContext.xml ✅Succeeded View
xml/System.CommandLine.Completions/TokenCompletionContext.xml ✅Succeeded View
xml/System.CommandLine.Help/HelpBuilder+Default.xml ✅Succeeded View
xml/System.CommandLine.Help/HelpBuilder.xml ✅Succeeded View
xml/System.CommandLine.Help/HelpBuilderExtensions.xml ✅Succeeded View
xml/System.CommandLine.Help/HelpContext.xml ✅Succeeded View
xml/System.CommandLine.Help/HelpSectionDelegate.xml ✅Succeeded View
xml/System.CommandLine.Help/TwoColumnHelpRow.xml ✅Succeeded View
xml/System.CommandLine.IO/IStandardError.xml ✅Succeeded View
xml/System.CommandLine.IO/IStandardIn.xml ✅Succeeded View
xml/System.CommandLine.IO/IStandardOut.xml ✅Succeeded View
xml/System.CommandLine.IO/IStandardStreamWriter.xml ✅Succeeded View
xml/System.CommandLine.IO/StandardStreamWriter.xml ✅Succeeded View
xml/System.CommandLine.IO/SystemConsole.xml ✅Succeeded View
xml/System.CommandLine.IO/TestConsole.xml ✅Succeeded View
xml/System.CommandLine.Invocation/ICommandHandler.xml ✅Succeeded View
xml/System.CommandLine.Invocation/IInvocationResult.xml ✅Succeeded View
xml/System.CommandLine.Invocation/InvocationContext.xml ✅Succeeded View
xml/System.CommandLine.Invocation/InvocationMiddleware.xml ✅Succeeded View
xml/System.CommandLine.Invocation/MiddlewareOrder.xml ✅Succeeded View
xml/System.CommandLine.Parsing/ArgumentResult.xml ✅Succeeded View
xml/System.CommandLine.Parsing/CommandLineStringSplitter.xml ✅Succeeded View
xml/System.CommandLine.Parsing/CommandResult.xml ✅Succeeded View
xml/System.CommandLine.Parsing/OptionResult.xml ✅Succeeded View
xml/System.CommandLine.Parsing/ParseArgument`1.xml ✅Succeeded View
xml/System.CommandLine.Parsing/ParseError.xml ✅Succeeded View
xml/System.CommandLine.Parsing/ParseResult.xml ✅Succeeded View
xml/System.CommandLine.Parsing/ParseResultExtensions.xml ✅Succeeded View
xml/System.CommandLine.Parsing/ParserExtensions.xml ✅Succeeded View
xml/System.CommandLine.Parsing/SymbolResult.xml ✅Succeeded View
xml/System.CommandLine.Parsing/TokenType.xml ✅Succeeded View

This comment lists only the first 50 files in the pull request.

xml/System.CommandLine.Binding/BoundValue.xml

  • Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NoFoundParent] Found no member can be inherited by key:ToString for uid: System.CommandLine.Binding.BoundValue.ToString.
  • Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NoFoundDocs] Inheridoc tag exists but no inheritdoc found for uid:System.CommandLine.Binding.BoundValue.ToString.

xml/System.CommandLine.Builder/CommandLineBuilderExtensions.xml

  • Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_InvalidTagsForStatic] Inheridoc should not use on static object for uid:System.CommandLine.Builder.CommandLineBuilderExtensions.ParseResponseFileAs(System.CommandLine.Builder.CommandLineBuilder,System.CommandLine.Parsing.ResponseFileHandling).
  • Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_InvalidTagsForStatic] Inheridoc should not use on static object for uid:System.CommandLine.Builder.CommandLineBuilderExtensions.UseVersionOption(System.CommandLine.Builder.CommandLineBuilder,System.String[]).

xml/System.CommandLine.Parsing/Parser.xml

  • Line 0, Column 0: [Suggestion: disallowed-html-tag - See documentation] HTML tag 'seealso' isn't allowed. Replace it with approved Markdown or escape the brackets if the content is a placeholder.

xml/System.CommandLine.Parsing/ResponseFileHandling.xml

  • Line 0, Column 0: [Suggestion: ECMA2Yaml_Enum_NoRemarks] Please note: <remarks> node on Enum fields will be ignored.

xml/System.CommandLine.Parsing/Token.xml

  • Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NoFoundParent] Found no member can be inherited by key:Equals(System.Object) for uid: System.CommandLine.Parsing.Token.Equals(System.Object).
  • Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NoFoundParent] Found no member can be inherited by key:GetHashCode for uid: System.CommandLine.Parsing.Token.GetHashCode.
  • Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NoFoundDocs] Inheridoc tag exists but no inheritdoc found for uid:System.CommandLine.Parsing.Token.GetHashCode.
  • Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NoFoundParent] Found no member can be inherited by key:ToString for uid: System.CommandLine.Parsing.Token.ToString.
  • Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NoFoundDocs] Inheridoc tag exists but no inheritdoc found for uid:System.CommandLine.Parsing.Token.ToString.

xml/System.CommandLine/ArgumentArity.xml

  • Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NoFoundParent] Found no member can be inherited by key:Equals(System.Object) for uid: System.CommandLine.ArgumentArity.Equals(System.Object).
  • Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NoFoundParent] Found no member can be inherited by key:GetHashCode for uid: System.CommandLine.ArgumentArity.GetHashCode.
  • Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NoFoundDocs] Inheridoc tag exists but no inheritdoc found for uid:System.CommandLine.ArgumentArity.GetHashCode.

xml/System.CommandLine/IdentifierSymbol.xml

  • Line 0, Column 0: [Suggestion: disallowed-html-tag - See documentation] HTML tag 'see' isn't allowed. Replace it with approved Markdown or escape the brackets if the content is a placeholder.

xml/System.CommandLine/Option`1.xml

  • Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NoFoundParent] Found no member can be inherited by key:#ctor(System.String[],System.String) for uid: System.CommandLine.Option`1.#ctor(System.String[],System.String).
  • Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NoFoundParent] Found no member can be inherited by key:#ctor(System.String,System.Func{`0},System.String) for uid: System.CommandLine.Option`1.#ctor(System.String,System.Func{`0},System.String).
  • Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NoFoundParent] Found no member can be inherited by key:#ctor(System.String[],System.Func{`0},System.String) for uid: System.CommandLine.Option`1.#ctor(System.String[],System.Func{`0},System.String).
  • Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NoFoundParent] Found no member can be inherited by key:#ctor(System.String,System.CommandLine.Parsing.ParseArgument{`0},System.Boolean,System.String) for uid: System.CommandLine.Option`1.#ctor(System.String,System.CommandLine.Parsing.ParseArgument{`0},System.Boolean,System.String).
  • Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NoFoundParent] Found no member can be inherited by key:#ctor(System.String[],System.CommandLine.Parsing.ParseArgument{`0},System.Boolean,System.String) for uid: System.CommandLine.Option`1.#ctor(System.String[],System.CommandLine.Parsing.ParseArgument{`0},System.Boolean,System.String).

For more details, please refer to the build report.

Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report.

For any questions, please:

@eiriktsarpalis
Copy link
Member

I'm assuming this is porting XML documentation from https://github.com/dotnet/command-line-api. From a triaging perspective, who would be accountable docs issues and PRs filed in System.CommandLine? We might want to add an area-System.CommandLine label.

cc @jonsequitur @gewarren @carlossanlop

@jonsequitur
Copy link

I'll handle issues filed in https://github.com/dotnet/command-line-api.

@gewarren
Copy link
Contributor

@jonsequitur There are some XML tag issues. Should we fix them here in the docs repo, or in the /// source? We have the "edit" button enabled for the .NET API ref docs, so other changes might creep into the docs repo too.

@jonsequitur
Copy link

What tool produces these warnings? Are other repos validating this closer to the source code?

@gewarren
Copy link
Contributor

What tool produces these warnings? Are other repos validating this closer to the source code?

The HTML sanitization happens as part of the docs build system, so no, I don't think other repos are validating the tags closer to the source code. It is a downside of having the /// source be the source of truth. But there are upsides too, of course.

<Parameters />
<Docs>
<summary>
Initializes a new instance of the Parser class with using the default <seealso cref="T:System.CommandLine.RootCommand" />.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Initializes a new instance of the Parser class with using the default <seealso cref="T:System.CommandLine.RootCommand" />.
Initializes a new instance of the <see cref="T:System.CommandLine.Parsing.Parser" /> class using the default <see cref="T:System.CommandLine.RootCommand" />.

</ReturnValue>
<Docs>
<summary>
The configuration on which the parser's grammar and behaviors are based.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.

</Parameters>
<Docs>
<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>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<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>

<Docs>
<param name="alias">The alias to add.</param>
<summary>
Adds an alias. Multiple aliases can be added, most often used to provide a shorthand alternative.
Copy link
Contributor

@gewarren gewarren Mar 23, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Adds an alias. Multiple aliases can be added, most often used to provide a shorthand alternative.
Adds an alias. Aliases can provide a shorthand alternative or simulate case-insensitivity, for example.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are other uses for aliases, such as to provide an alternate spelling of a long-form option name (--serialize, --serialise, for example), or to simulate case-insensitivity.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, I updated the suggestion.

<summary>
Adds an alias. Multiple aliases can be added, most often used to provide a shorthand alternative.
</summary>
<remarks>To be added.</remarks>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<remarks>To be added.</remarks>
<remarks>You can add multiple aliases for a symbol.</remarks>

</Parameters>
<Docs>
<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>
Copy link
Contributor

@gewarren gewarren Mar 23, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<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>

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

to parse like any other token --> to parse them like any other token

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I updated the wording to be more explicit.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

to parse text in square brackets like any other token.

To be a directive, the text in square brackets has to be the first text on the command line; text in square brackets anywhere else is never treated like a directive.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay, updated again.

</Parameters>
<Docs>
<param name="builder">To be added.</param>
<param name="value">To be added.</param>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<param name="value">To be added.</param>
<param name="value">
<see langword="true" /> to place all tokens following <c>--</c> into the <see cref="P:System.CommandLine.Parsing.ParseResult.UnparsedTokens" /> collection. <see langword="false" /> to treat all tokens following <c>--</c> as command arguments, even if they match an existing option.</param>

Determines the behavior when parsing a double dash (<c>--</c>) in a command line.
</summary>
<returns>To be added.</returns>
<remarks>When set to <see langword="true" />, all tokens following <c>--</c> will be placed into the <see cref="P:System.CommandLine.Parsing.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>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<remarks>When set to <see langword="true" />, all tokens following <c>--</c> will be placed into the <see cref="P:System.CommandLine.Parsing.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>
<remarks>To be added.</remarks>

</Parameters>
<Docs>
<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>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<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>

<summary>To be added.</summary>
<returns>The same instance of <see cref="T:System.CommandLine.Builder.CommandLineBuilder" />.</returns>
<remarks>To be added.</remarks>
<inheritdoc cref="P:System.CommandLine.Builder.CommandLineBuilder.ResponseFileHandling" />
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think the cref attribute is currently supported in docs for inheritdoc - also not sure if you can inherit property doc comments for a method?

</summary>
<returns>The same instance of <see cref="T:System.CommandLine.Builder.CommandLineBuilder" />.</returns>
<remarks>To be added.</remarks>
<altmember cref="T:System.CommandLine.DirectiveCollection" />
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<altmember cref="T:System.CommandLine.DirectiveCollection" />
<related type="Article" href="/dotnet/standard/commandline/syntax#directives">Command-line directives</related>
<altmember cref="T:System.CommandLine.DirectiveCollection" />

@carlossanlop
Copy link
Contributor

carlossanlop commented Mar 29, 2022

I'm assuming this is porting XML documentation from https://github.com/dotnet/command-line-api. From a triaging perspective, who would be accountable docs issues and PRs filed in System.CommandLine? We might want to add an area-System.CommandLine label.

I agree with @eiriktsarpalis that we should add the new area label.

Also, we need to add you @jonsequitur (or preferably an area owner group, if you can share one) to the CODEOWNERS file of this repo, so you get notified when an issue or PR is opened for files in your area.

@tdykstra tdykstra merged commit 4b41a17 into main Mar 29, 2022
@tdykstra tdykstra deleted the commandline branch March 29, 2022 23:19
tdykstra added a commit that referenced this pull request Mar 29, 2022
@v-alje
Copy link
Contributor Author

v-alje commented Mar 30, 2022

@tdykstra Do you need me to recreate this?

@tdykstra
Copy link
Contributor

No, I closed the revert PR. I made the revert PR when I remembered that @gewarren's comments hadn't been addressed. But after discussing with her I decided to make the changes in the /// comments instead and then you can do whatever you do to apply the updated /// comments.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

9 participants