CS1584+CS1658/CS0081 when using constructed generic types in XML comments

[paulomorgado]

This code:

/// <summary>
/// A <see cref="TaskCompletionSource{IReadOnlyDictionary{string, object}}" /> object that handles the completion of the state machine execution.
/// </summary>
private readonly TaskCompletionSource<IReadOnlyDictionary<string, object>> completion;

Generates 4 CS1658 warning caused by a CS0081 error in the comment line warnings both in VS2015 and VS2017 and an extra CS1584 warning in VS2017.

By the way, where is the documentation for these errors/warnings?

[jnm2]

Constructed generic types are not supported in XML documentation, to my irritation.
Though in your example copying the entire type into the documentation does seem like a waste since people will be viewing the type twice in a row now, no matter where they are reading the documentation.

[paulomorgado]

to my irritation
Our irritation! 😄

I'm trying to work out phrasing that inform unexperienced developers that asynchronous methods return a Task and everyone that the important part is the Task<T>.Result.

[gafter]

I'm not sure if this is intended as a language proposal, a language question, or if it belongs in the Roslyn repo as a comment about the behavior of the compiler.

[paulomorgado]

Neither do I!

Should that be wrong? What does the spec say about that?

[aluanhaddad]

This is definitely a pain point. I would love to see support for this.

[sharwell]

Currently the compiler does not allow a documentation comment to directly reference an instantiated generic type. For the purpose of hyperlinking in the resulting documentation, this seems to make sense. However, documentation includes more than just a simple hyperlink. I can certainly see value in the ability to reference an instantiated generic type which displays using the type as-referenced, but links to the original type definition.

From what I can tell, the spec neither requires nor forbids this ability. I believe it would make sense to formalize the desired behavior as a language proposal prior to implementing it within one specific compiler.

[jnm2]

As far as hyperlinking goes, I'd assume it would hyperlink to the .GetGenericTypeDefinition() of the type.

[sharwell]

@jnm2 Yes, that's what I meant by linking to the original type definition.

[paulomorgado]

@sharwell,

I does allows IReadOnlyDictionary{string, object}. Just doesn't allow TaskCompletionSource{IReadOnlyDictionary{string, object}}.

[jnm2]

Thought a documentation generator could be free to, if it wanted, insert links inside links exactly as what happens when you'd go to definition in the IDE: IReadOnlyDictionary<string, MyType>

@paulomorgado It actually doesn't allow IReadOnlyDictionary{string, object} the way you're thinking; it just aliases TKey as string and TValue as object. It doesn't show String for VB.NET and string for C#, for example. Importantly, it doesn't allow a . in the type parameter alias, as in, Task<System.String>, because no type parameter can be named System.String.

[paulomorgado]

⚡️ 💡

Now it makes sense why it's doing what's doing.

But it should be fixed.

[kwaclaw]

The current SandCastle help compiler already does the desired thing for constructed generic types when they are read from the assembly and not from the doc comment. E.g. a return type of IDictionary<string, object> is shown as the same, but the link points to the documentation for the generic type IDictionary<TKey, TValue>. Extending this behaviour to doc comments would be consistent.