Docs improvements #2709
Docs improvements #2709
Conversation
|
|
||
| /// <summary> | ||
| /// Represents all of the options for the command, inherited options that have been applied to any of the command's ancestors. | ||
| /// Gets all of the options for the command, including inherited options that have been applied to any of the command's ancestors. |
There was a problem hiding this comment.
IIRC, this does not include inherited options.
| /// <exception cref="NotSupportedException">Thrown if this method is called by Option-owned ArgumentResult.</exception> | ||
| /// <exception cref="ArgumentOutOfRangeException"><c>numberOfTokens - Value</c> must be at least 1.</exception> | ||
| /// <exception cref="InvalidOperationException">This method is called more than once.</exception> | ||
| /// <exception cref="NotSupportedException">This method is called by Option-owned ArgumentResult.</exception> |
There was a problem hiding this comment.
In practice, this exception is thrown if an Option has a CustomParser delegate that receives an ArgumentResult as a parameter and calls the OnlyTake method of that ArgumentResult.
| /// <summary> | ||
| /// The token that was parsed to specify the directive. | ||
| /// Gets the token that was parsed to specify the directive. | ||
| /// </summary> | ||
| public Token Token { get; } |
There was a problem hiding this comment.
This is unclear in the case where the command line has multiple directive tokens with the same name: [name] [name:value1] [name:value2]. IIRC the library parses those and collects all of them to the same DirectiveResult instance, whose Values property then is { "name1", "name2" } (not sure whether the null value is just lost entirely). But which token do you get in the Token property then?
| /// int lastElement = someArray[^1]; // lastElement = 5 | ||
| /// </code> | ||
| /// </remarks> | ||
| internal readonly struct Index : IEquatable<Index> |
There was a problem hiding this comment.
Because Index and Range are internal types here, and .NET documents the corresponding types in the System namespace, I don't think it is necessary to spend much time on improving their API docs.
There was a problem hiding this comment.
There was a problem hiding this comment.
Do you mean the docs tools read the System.Index and System.Range documentation from here, rather than from the dotnet/runtime repository? That seems like a bug that should be fixed in the tools; imagine if the documentation is later edited in dotnet/runtime and the edits don't get published because they are overridden.
There was a problem hiding this comment.
Yes, it's a bit complex, but because the System.CommandLine package uses its compiler-generated XML file as the source of truth for docs, we import the XML doc file when we run the CI updates. And that will always overwrite whatever is already in dotnet-api-docs. For the APIs coming from dotnet/runtime, that package does not use the compiler generated XML file as the source of truth. So updates for Index/Range should always occur in dotnet-api-docs, not dotnet/runtime.
There was a problem hiding this comment.
Also, there was an internal customer suggestion I logged to the ingestion pipeline for docs that XML comments should only be imported from XML files where the file name matches the assembly name. But it wasn't fixed. So this is the next best option.
There was a problem hiding this comment.
Would an alternative be just deleting the xml docs from this file altogether?
There was a problem hiding this comment.
That might work, but there might be an analyzer that checks for existence of docs?
There was a problem hiding this comment.
I'm not aware of any analyzers that would warn about missing documentation. The compiler warning CS1591 won't trigger because these classes are internal.
2 participants
Contributes to dotnet/dotnet-api-docs#11392.