<see> IntelliSense offers keyword types for generic parameters, producing warnings

[SLaks]

Source:

/// <see cref="Func{bo"/>

IntelliSense will show bool, which will produce the following two warnings when selected:

1. CS1658 Type parameter declaration must be an identifier not a type. See also error CS0081.
2. CS1584 XML comment has syntactically incorrect cref attribute 'Action{bool}'

On a related note, why does this syntax produce an error when referencing types, but work fine in types in method arguments?

[sharwell]

Func{bool} is an instantiation of a generic type. The type is defined as Func{T}.

Keyword types are fine in documentation comments as long as they are actually correct references, and not being used as generic arguments. Func{bool} may appear in a method signature if the method is not generic and has a Func{bool} parameter.

[SLaks]

@sharwell: But why are there different rules for specifying constructed generic types as method parameter types vs. as standalone types?

[sharwell]

@SLaks It's required for documentation comments to be able to differentiate the following:

void Method(Func<int> intFunction)
void Method(Func<bool> boolFunction)

There is no need to be able to use <see cref="Func{int}"/> because there is no documentation which is specifically for the constructed generic type. Documentation for Func<T> is only provided for the non-generic type. For some reason the documentation compiler ignores the actual text of the identifier representing the generic type parameter, so you can write Func{T} or Func{TResult} to reference the same open generic type.

[sharwell]

By the way, this bug is certainly a bug. bool should not be offered for code completion in the context you described originally.

[SLaks]

@sharwell I know. But why is int or bool legal there? Why the inconsistency?

[sharwell]

@SLaks Can you provide a specific example of where you are seeing an inconsistency? I'm not sure I understand your question.

[SLaks]

I mean that <see cref="Func{bool}"/> is illegal, whereas <see cref="MyMethod(Func{bool})"/> is not.

[sharwell]

There is no documentation for a Func<bool>. The documentation is published for the open generic type Func<TResult>. If you define a method void MyMethod(Func<bool> arg), the parameter has the closed generic type Func<bool>, not the open generic type Func<TResult>. The references to the types in documentation do not appear the same because you are not referencing the same type (the same way typeof(Func<>) != typeof(Func<bool>)).

[SLaks]

No.

<see cref="Func{Boolean}"/> is perfectly fine. It's a reference to a specific constructed generic type. In documentation, that means links to two different types, as seen in https://msdn.microsoft.com/en-us/library/dd991174

[sharwell]

@SLaks This is where things get a bit interesting. When referencing an open generic type, the documentation compiler requires an identifier but does not actually check the content of the identifier. It's like writing <see cref="Func{}"/>, except that some identifier has to be included. Your <see> element compiles to the following in the generated XML for the project:

<see cref="T:System.Func`1"/>

It's no different from <see cref="Func{TResult}"/>.

[stimpy77]

This is bothering me. I have a requirement for:

public void Foo(object bar)

.. for which I need to document:

The parameter bar must be an IDictionary<string, object>, or else it must be any object with public properties that can be mapped to an IDictionary<string, object>.

I realize that an overload with IDictionary<string, object> can accommodate this, but an overload should not be required solely in order to accommodate summary documentation. It should be possible to include generic implementation references in summary documentation.

[sharwell]

@stimpy77 see dotnet/csharplang#401 for that feature request 👍