在 C# XML 文档中引用泛型类型的泛型类型？

Posted 2023-02-19

【中文标题】在 C# XML 文档中引用泛型类型的泛型类型？

【英文标题】：Referring to a generic type of a generic type in C# XML documentation?

【发布时间】：2010-10-15 15:50:16

【问题描述】：

为谓词助手类编写一些 XML 文档。但我不知道我可以引用Expression<Func<T, bool>> 而不会出现语法错误。甚至可能吗？我试过这个：

<see cref="ExpressionFuncT, bool"/>

但我在T, bool 下看到一条红色波浪线。这虽然有效：

<see cref="ExpressionTDelegate"/>

有人知道吗？

---

更新：

给出的答案（我接受了）似乎确实有效。但现在我开始收到很多关于无法解决问题的警告。我有一个名为ExpressionBuilder<T> 的类，它与Expression<Func<T, bool>> 一起使用很多。所以我当然想在我的 XML cmets 中引用它。

我已经尝试了我知道的两个版本：

<see cref="Expression&lt;Func&lt;T, Boolean&gt;&gt;"/>
<see cref="ExpressionFuncT, Boolean"/>

但两者都不起作用。 （在最后一个上，ReSharper 在T,Boolean 下放了一个蓝色波浪线，我在编译的所有地方都收到了两个警告，上面写着：

“blah blah”上的 XML 注释具有无法解析的 cref 属性“Expression>” 类型参数声明必须是标识符而不是类型。另请参阅错误 CS0081。

在我尝试参考Range<Nullable<DateTime>> 的某个地方遇到同样的问题（Range<DateTime?> 也不起作用。使用 和 < >）

我不应该引用这些泛型吗？

【问题讨论】：

我正要问同样的问题。我花了一段时间才找到这个，因为标题不是很关键字。我可以建议，“我如何在 C# XML 文档中引用泛型类型的泛型类型”？您还可以添加“泛型”标签。我没有代表自己做。

在 VS2015，Reshaper 9 中工作正常

消息显示“类型参数声明必须是标识符而不是类型”；例如，如果你有ListInt32，它应该是ListT，因为在代码库的某个地方没有真正的ListInt32 类，只有ListT。 Int32 是一个类型，T 是一个标识符。

【参考方案1】：

我是来用这个的：

<see cref=""EqualityComparerT.Default"">EqualityComparer&lt;<typeparamref name=""TSource""/>&gt;.Default</see>

在此处应用于您的 OP 结果：

<see cref="System.Linq.Expressions.ExpressionTDelegate">Expression&lt;Func&lt;<typeparamref name="TSource"/>, Boolean&gt;&gt;.</see>

这是 IntelliSense 弹出窗口的图像：

【参考方案2】：

我在堆栈溢出时尝试了所有方法，以获得适用于多种情况的结果。这是一个适合我的解决方案。 （这对其他人来说是主观的。）

产生可点击的链接。 将鼠标悬停在标识符上有效。 正确生成 .xml 文件。 在智能感知中不会产生错误。 适用于可为空的泛型类型参数。 在 Resharper 中工作，它是内置的 XML Doc 窗口（Resharper -> 编辑 -> 显示快速文档） 适用于 Atomineer Pro Documentaion Visual Studio Extension 的 XAM Doc Preview。 适用于泛型类型的泛型类型。

示例 #1

  /// <summary>
  ///  This instance field holds a reference to the
  ///  <see cref="ConcurrentDictionaryDecimal, Boolean"/> as
  ///  <see cref="T:ConcurrentDictionary&lt;decimal, bool?&gt;"/> that contains
  ///  the list of all PDF's that are currently opened and being displayed.
  /// </summary>
  private ConcurrentDictionary<decimal, bool?> openedPdfs = default!;

  Note: 
    The ConcurrentDictionaryDecimal, Boolean will correctly produce a
    clickable link of ConcurrentDictionaryTKey, TValue on hovering while
    T:ConcurrentDictionary&lt;decimal, bool?&gt; makes sure the reader gets
    information on what type TKey and TValue are.

示例 #2（使用“T”）

  /// <summary>
  ///  This instance field holds a reference to the
  ///  <see cref="ConcurrentDictionaryTKey, TValue"/> as
  ///  <see cref="T:ConcurrentDictionary&lt;decimal, bool?&gt;"/> that contains
  ///  the list of all PDF's that are currently opened and being displayed.
  /// </summary>
  private ConcurrentDictionary<decimal, bool?> openedPdfs = default!;

【参考方案3】：

不要使用空的 see 元素 (<see cref="..." />)。相反，将文本放在 see 元素中

<see cref="IEnumerableT">IEnumerable</see>&lt;<see cref="..."/>$gt;

【参考方案4】：

我现在遇到了这个问题，因为我有一个返回 List<List<byte>> 的函数。是的，它很丑，但我没有写它。标准免责声明，我知道。

无论如何，在带有 R# Ultimate 2017.1 的 VS 2017 中，此文档注释...

<returns><see cref="ListListByte" /> of split frames</returns>

...给我一个语法错误。不过这...

<returns><see><cref>ListListbyte</cref></see> of split frames</returns>

...没有。 Eeeenteresting。

还丑吗？是的。

像丑？我认为这比我自己使用< 和> 更可怕......

【参考方案5】：

在 XML 文档中似乎无法引用泛型的泛型，因为实际上，无法引用任何特定类型的泛型。

Lasse V Karlsen 的 answer 让我点击了：

如果你写<see cref="IEnumerableInt32" />，编译器只是使用“Int32”作为类型参数名称，而不是类型参数。写<see cref="IEnumerableHelloWorld" /> 也可以。这是有道理的，因为 MSDN 中没有您的文档可以链接到的“IEnumerable of int”的特定页面。

要正确记录您的课程，我认为您必须编写如下内容：

<summary>
Returns an <see cref="IEnumerableT" /> of <see cref="KeyValuePairT,U" /> 
of <see cref="String" />, <see cref="Int32" />.
</summary>

希望你喜欢文字。

【讨论】：

不，我讨厌文字，这就是我问这个问题的原因。哦，好吧......也许在未来版本的 xml-doc 中：p

不幸的是，2020 年没有任何改变，而这似乎仍然是唯一真正的解决方案。仍然无法在 cref XML cmets 中引用像 Nullable<int> 这样的泛型类型。

【参考方案6】：

您希望它链接到什么？

文档中没有 Expression<Func<T>> 这样的东西，所以很明显，指向它的链接是行不通的。

您可以链接到Expression<TDelegate>，因为它存在。

至于什么可行或不可行，以下都不适用于我的 Visual Studio 2008 / .NET 3.5：

/// <see cref="Expression&lt;Func&lt;T&gt;&gt;"/>.
/// <see cref="ExpressionFuncT"/>.

但这有效：

/// <see cref="ExpressionT"/>.

显然，泛型类型参数不必与声明中的相同。

【讨论】：

那么有没有办法用特定类型参数来引用泛型类型？就像我有一个返回 List> 的函数一样，我只能说它返回了 List？

那是因为“String”只是用作泛型类型名称。试试 List ，它的效果也一样好。

【参考方案7】：

// Use "&lt;" instead of "<" symbol and "&gt;" instead of ">" symbol.

// Sample:

<see cref="Expression&lt;Func&lt;T, bool&gt;&gt;"/>

【讨论】：

哦，天哪……这很丑……但它确实有效 =/ 为什么它接受一种类型的 而不是更多？

确定什么？就像我说的，当使用ExpressionTDelegate 或例如ListString 时，我没有看到红色波浪线。实际上，当我写 。然后当我写 List 并按 Enter 键时，它会自动完成 ListT。

请注意，红色波浪线不是 Visual Studio，很可能是 ReSharper 或 Refactor！亲，他们有时也会感到困惑。相信编译器。

Visual Studio 2010 会用警告标记此类内容。显然，MS 认为在 2008 年不这样做是一个错误。

不需要>，这是格式良好的XML：<see cref="Expression<Func<T, bool>>"/>