如何在xml文档中引用泛型类和方法

Question

编写xml文档时，您可以使用<see cref="something">something</see>，当然这是有效的。但是，如何引用具有泛型类型的类或方法？

public class FancyClass<T>
{
  public string FancyMethod<K>(T value) { return "something fancy"; }
}

如果我要在某处编写xml文档，我将如何引用这个花哨的类？如何引用FancyClass<string>？这个方法怎么样？

例如，在另一个类中，我想让用户知道我将返回FancyClass<int>的实例。我怎么能看到cref的东西？

Answer 1

参考方法：

/// <see cref="FancyClass{T}.FancyMethod{K}(T)"/> for more information.

Answer 2

/// <summary>Uses a <see cref="FancyClass{T}" /> instance.</summary>

BTW，它出现在.Net Framework 2.0和3.0的MSDN文档中，但它在version 3.5

中消失了

Answer 3

到目前为止，所有答案都没有完全适用于我。 ReSharper不会将see标签转换为 Ctrl +可点击链接（例如），除非它完全解析。

如果OP中的方法位于名为Test的名称空间中，则显示的方法的完全解析链接为：

<see cref="M:Test.FancyClass`1.FancyMethod``1(`0)"/>

由于你可以解决，在类类型参数的数量之前应该只有一个反引号，然后在方法类型参数的数量之前有两个反引号，那么参数是具有适当数字的零索引参数反叛。

因此我们可以看到FancyClass有一个类类型参数，FancyMethod有一个类型参数，FancyClass参数类型的对象将传递给方法。

您可以在此示例中更清楚地看到：

namespace Test
{
    public class FancyClass<A, B>
    {
        public void FancyMethod<C, D, E>(A a, B b, C c, D d, E e) { }
    }
}

链接变为：

M:Test.FancyClass`2.FancyMethod``3(`0,`1,``0,``1,``2)

或＆＃34;具有两个类型参数的类，其具有三个类型参数的方法，其中方法参数为ClassType1，ClassType2，MethodType1，MethodType2， MethodType3＆＃34;

作为补充说明，我没有在任何地方找到这个记录，而且我不是天才，编译器告诉我所有这些。您所要做的就是创建一个测试项目enable XML documentation，然后插入您想要编写链接的代码，并在其上放置XML doc注释（///）：< / p>

namespace Test
{
    public class FancyClass<T>
    {
        ///
        public string FancyMethod<K>(T value) { return "something fancy"; }
    }

    public class Test
    {
        public static void Main(string[] args) { }
    }
}

然后构建您的项目，输出的XML文档包含属性doc下的members - ＆gt; member - ＆gt; name元素中的链接：< / p>

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>Test</name>
    </assembly>
    <members>
        <member name="M:Test.FancyClass`1.FancyMethod``1(`0)">

        </member>
    </members>
</doc>

Answer 4

TL; DR：

  

“我如何引用FancyClass<T>？”

   /// <see cref="FancyClass{T}"/>

  

“FancyClass<T>.FancyMethod<K>(T value)怎么样？”

   /// <see cref="FancyClass{T}.FancyMethod{K}(T)"/>

  

“我如何引用FancyClass<string>？”

   /// <see cref="SomeType.SomeMethod(FancyClass{string})"/>
   /// <see cref="FancyClass{T}"/> whose generic type argument is <see cref="string"/>

虽然可以引用其签名包含FancyClass<string>的方法（例如作为参数类型），但不能直接引用此类已关闭的泛型类型。第二个例子解决了这个限制。 （例如在MSDN refence page for the static System.String.Concat(IEnumerable<string>) method上）。 ：

XML文档评论cref规则：

• 使用大括号{} 而不是<>尖括号括起泛型类型参数列表。这使您无法将后者转义为<和> - 请记住，文档注释是XML！

• 如果您为类型添加前缀（例如T: ，则为方法添加M:，为属性添加P:，F:对于字段），编译器不会对引用执行任何验证，而只是将cref属性值直接复制到文档XML输出。因此，您必须使用适用于此类文件的特殊"ID string" syntax：始终使用完全限定的标识符，并使用反引号来引用泛型类型参数（`n类型，{{1方法）。

• 如果省略前缀，则会应用常规语言命名规则：您可以删除有``n语句的命名空间，并且可以使用该语言的类型关键字，例如using代替int。此外，编译器将检查引用的正确性。

XML文档评论System.Int32备忘单：

cref

Answer 5

进一步来自Lasse和T.B.C的答案：

/// <see cref="T:FancyClass`1{T}"/> for more information.

/// <see cref="M:FancyClass`1{T}.FancyMethod`1{K}(T)"/> for more information.

还将正确提供工具提示，而其版本则使用花括号进行渲染。

Answer 6

/// Here we discuss the use of <typeparamref name="TYourExcellentType"/>.
/// <typeparam name="TYourExcellentType">Your exellent documentation</typeparam>

Answer 7

/// <see cref="FancyClass&lt;T>.FancyMethod&lt;K>(T)"/> for more information.

Answer 8

这是我在别处给出的答案。它也适用于类和方法。

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

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

示例 #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!;