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

Question

为谓词助手类编写一些 XML 文档。但我不知道我可以在Expression<Func<T, bool>>没有语法错误的情况下引用 an 。甚至可能吗？我试过这个：

<see cref="Expression{Func{T, bool}}"/>

但是我得到了一条红色的波浪线{T, bool}}。这虽然有效：

<see cref="Expression{TDelegate}"/>

有人有线索吗？

更新：

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

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

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

但两者都不起作用。（在最后一个上，ReSharper 在{T,Boolean}}我使用过的所有地方都在编译时收到了两个警告，上面写着：

'blah blah' 上的 XML 注释具有无法解析的 cref 属性 'Expression>'

类型参数声明必须是标识符而不是类型。另请参阅错误 CS0081。

在我试图引用的某个地方遇到同样的问题Range<Nullable<DateTime>>（Range<DateTime?>也没有工作。使用 { } 和 with < >）

我不应该参考这些泛型吗？

score 47 · Accepted Answer

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

Lasse V Karlsen 的回答让我点击了：

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

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

<summary>
Returns an <see cref="IEnumerable{T}" /> of <see cref="KeyValuePair{T,U}" /> 
of <see cref="String" />, <see cref="Int32" />.
</summary>

我希望你喜欢文字。

score 12 · Accepted Answer

您究竟希望它链接到什么？

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

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

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

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

但这有效：

/// <see cref="Expression{T}"/>.

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

score 3 · Accepted Answer

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

// Sample:

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

score 1 · Accepted Answer

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

无论如何，在带有 R# Ultimate 2017.1 的 VS 2017 中，这个文档评论......

<returns><see cref="List{List{Byte}}" /> of split frames</returns>

...给我一个语法错误。然而，这...

<returns><see><cref>List{List{byte}}</cref></see> of split frames</returns>

...才不是。 有趣的。

还是丑？是的。

一样丑？<我认为它没有使用和我自己那么可怕>......

score 1 · Accepted Answer

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

<see cref="IEnumerable{T}">IEnumerable</see>&lt;<see cref="..."/>$gt;

score 0 · Accepted Answer

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

产生可点击的链接。
将鼠标悬停在标识符上有效。
正确生成 .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="ConcurrentDictionary{Decimal, 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 ConcurrentDictionary{Decimal, Boolean} will correctly produce a
    clickable link of ConcurrentDictionary{TKey, 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="ConcurrentDictionary{TKey, 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!;

score 0 · Accepted Answer

我来使用这个：

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

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

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

这是 IntelliSense 弹出窗口的图像：

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

7 回答 7

Related

Reference