在 XML 文档注释中引用通用类型

Question

我有这样的界面：

public IApiController<T> where T: IEntity
{
    /// <summary>
    /// Returns Entity with Id = <paramref name="id"/> of Class <typeparamref name="T"/>.
    /// </summary>
    public Task<ActionResult<T>> Get(int id);
}

在我的评论中，我想引用 T，所以当我有一个实现 IApiController<Developer> 的 DeveloperController 时，Intellisense 评论说：

"Returns 实体 ID = 类型开发人员的 ID"

但我只收到以下评论：

"Returns Id = 类型 T 的实体"

任何人都可以解释我做错了什么吗？

Answer 1

Can anybody explain me what I am doing wrong?

很难说，因为你的问题缺少一些重要的细节。但是，我怀疑您未包含在 post 中的代码看起来像这样：

/// <inheritdoc/>
class DeveloperController : IApiController<Developer>
{
    public Task<ActionResult<Developer>> Get(int id) { /* ... */ }
}

并且当您查看 Intellisense 时，您正在查看类型为 DeveloperController 的变量，而不是 IApiController<Developer>.

问题是，当 <inheritdoc/> 标记从原始泛型 class 继承 XML 注释时，<typeparameterref/> 元素必然仍然引用包含类型的类型参数，还有none。那时它只有 XML 注释本身，而不是用于构造通用 class.

的类型参数

所以，例如，在下面的代码中：

IApiController<Developer> o1 = ...;
DeveloperController o2 = o1;

o1.Get(1);
o2.Get(1);

当您将鼠标悬停在 o1.Get(1) 上时，Intellisense 将能够告诉您实际的类型参数，但当您将鼠标悬停在 o2.Get(1).

上时则不会

请注意，如果 DeveloperController 类型本身是泛型的，并且其类型参数用于接口继承的声明，当然还有实现，那么 Intellisense 将可以直接访问泛型类型参数，并且它会显示你所期望的。当然，使该类型通用可能与您的设计不兼容，因此在这种情况下这并没有多大帮助。但在其他情况下值得牢记。

还值得牢记 <typeparameterref/> 的这个限制，因为如果你有另一个场景，其中 DeveloperController class 是通用的，但它的类型参数是不是用于接口，而是用于 class 的其他一些通用方面，并且调用代码使用与用于接口的类型参数不同的类型，Intellisense 会显示错误的类型。

例如，您有：

/// <inheritdoc/>
class DeveloperController<T> : IApiController<Developer>
{
    public Task<ActionResult<Developer>> Get(int id) { /* ... */ }
}

，然后您使用类型参数为 bool 的 DeveloperController<T> class，Intellisense 将显示 "Returns Entity with Id = id Class 布尔值。"

显然，这并不理想，事实上我认为这是一个错误，但它可能是可以理解的。

在 XML 文档注释中引用通用类型

Reference the Generic Type in an XML Documentation comment

c#

xml-documentation