Question

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

<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＆gt;'无法解决的问题

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

在我试图引用的Range<Nullable<DateTime>>（Range<DateTime?>也没有用的地方也有同样的问题。{}和< >

我不应该提到这些类型的泛型吗？

Answer 1

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

Lasse V Karlsen的answer让我点击了它：

如果编写<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>

我希望你喜欢文字。

Answer 2

您希望它链接到什么地方？

文档中没有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}"/>.

显然，泛型类型参数与声明中的参数不一样。

Answer 3

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

// Sample:

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

Answer 4

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

无论如何，在VS 2017中使用R＃Ultimate 2017.1，这个文档评论......

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

...给我一个语法错误。但是，这......

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

......没有。 Eeeenteresting

还难看吗？是。

丑陋？我认为它比使用<和>本身更不可怕......

Answer 5

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

中

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

Answer 6

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

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

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

6 个答案: