-
Notifications
You must be signed in to change notification settings - Fork 1.6k
Adding commandline API #7859
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Adding commandline API #7859
Conversation
|
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. |
|
Docs Build status updates of commit 0e6af4f: ✅ Validation status: passedThis comment lists only the first 50 files in the pull request. xml/System.CommandLine.Binding/BoundValue.xml
xml/System.CommandLine.Builder/CommandLineBuilderExtensions.xml
xml/System.CommandLine.Parsing/Parser.xml
xml/System.CommandLine.Parsing/ResponseFileHandling.xml
xml/System.CommandLine.Parsing/Token.xml
xml/System.CommandLine/ArgumentArity.xml
xml/System.CommandLine/IdentifierSymbol.xml
xml/System.CommandLine/Option`1.xml
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:
|
|
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 |
|
I'll handle issues filed in https://github.com/dotnet/command-line-api. |
|
@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. |
|
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" />. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| 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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| 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> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| <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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| 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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| <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> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| <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> |
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| <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> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| <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> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| <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" /> |
There was a problem hiding this comment.
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" /> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| <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" /> |
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 Do you need me to recreate this? |
|
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. |
Summary
This pull request adds the CommandLine API reference for the System.CommandLine NuGet package.