Docs improvements

[gewarren]

Contributes to dotnet/dotnet-api-docs#11392.

[KalleOlaviNiemitalo]

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?

[gewarren]

Resolving to merge since I don't know the answer. I will unresolve after merge.

[jonsequitur]

IIRC the library parses those and collects all of them to the same DirectiveResult instance, whose Values property then is { "name1", "name2" }

This is correct.

(not sure whether the null value is just lost entirely). But which token do you get in the Token property then?

This is a bit of a rough edge, and there's a bug. I wrote a quick test to explore this.

• There's no null value in the Values property (which I think is reasonable but I could see an argument for it either way).
• The Token property contains the first instance of the directive and the Tokens property contains the others. This seems like a bug.

[gewarren]

@adamsitnik Could you review?

[gewarren]

Can someone from the team comment on the outstanding questions so I can move forward with this PR?

[adamsitnik]

LGTM, thank you @gewarren !

[gewarren]

@jonsequitur Could you merge it please? I don't have perms.