如何在xml文档中引用泛型类和方法-Java 学习之路

179

在编写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的东西呢？

7 回答

要参考方法：

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

回复于 2024-04-19T16:22:14+08:00

9
```
/// <summary>Uses a <see cref="FancyClass{T}" /> instance.</summary>
```
顺便说一句，它出现在.Net Framework 2.0和3.0的MSDN文档中，但它在version 3.5中消失了
回复于 2024-04-19T16:22:14+08:00
13
到目前为止，所有答案都没有完全适用于我 . 除非完全解析，否则ReSharper不会将see标记转换为Ctrl可点击链接（例如

） .

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

<see cref="M:Test.FancyClass1.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.FancyClass2.FancyMethod3(`0,`1,0,1,2)`

或者“具有两个类型参数的类，其具有三个类型参数的方法，其中方法参数为 ClassType1 ， ClassType2 ， MethodType1 ， MethodType2 ， MethodType3 ”

作为补充说明，我没有天才，编译器告诉了我这一切 . 您所要做的就是创建一个测试项目enable XML documentation，然后插入您想要编写链接的代码，并在其上添加XML文档注释的开头（ /// ）：
```
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文档包含属性 name 下 doc - > members - > member 元素中的链接：
```
<?xml version="1.0"?>
<doc>
    <assembly>
        <name>Test</name>
    </assembly>
    <members>
        <member name="M:Test.FancyClass`1.FancyMethod``1(`0)">

        </member>
    </members>
</doc>
```
回复于 2024-04-19T16:22:14+08:00
235
TL; DR：

“我如何引用FancyClass <T>？”
```
/// <see cref="FancyClass{T}"/>
```
“FancyClass <T> .FancyMethod <K>（T值）怎么样？”
```
/// <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规则：
- Surround the generic type parameter list with curly braces {} 而不是 <> 尖括号 . 这使您免于将后者转义为 < 和 > - 请记住，文档注释是XML！
- If you include a prefix (such as T: 用于类型， M: 用于方法， P: 用于属性， F: 用于字段），编译器不会对引用执行任何验证，而只是将 cref 属性值直接复制到文档XML输出 . 因此，您必须使用适用于此类文件的特殊"ID string" syntax：始终使用完全限定标识符，并使用反引号来引用泛型类型参数（类型为 ``n，方法为 ```n ） .
- If you omit the prefix ，适用常规语言命名规则：您可以删除具有 using 语句的命名空间，并且可以使用语言的类型关键字，例如 int 而不是 System.Int32 . 此外，编译器将检查引用的正确性 .
XML文档评论cref备忘单：
```
namespace X
{
    using System;

    /// <see cref="I1"/>  (or <see cref="X.I1"/> from outside X)
    /// <see cref="T:X.I1"/>
    interface I1
    {
        /// <see cref="I1.M1(int)"/>  (or <see cref="M1(int)"/> from inside I1)
        /// <see cref="M:X.I1.M1(System.Int32)"/>
        void M1(int p);

        /// <see cref="I1.M2{U}(U)"/>
        /// <see cref="M:X.I1.M2``1(``0)"/>
        void M2<U>(U p);

        /// <see cref="I1.M3(Action{string})"/>
        /// <see cref="M:X.I1.M3(System.Action{System.String})"/>
        void M3(Action<string> p);
    }

    /// <see cref="I2{T}"/>
    /// <see cref="T:X.I2`1"/>
    interface I2<T>
    {
        /// <see cref="I2{T}.M1(int)"/>
        /// <see cref="M:X.I2`1.M1(System.Int32)"/>
        void M1(int p);

        /// <see cref="I2{T}.M2(T)"/>
        /// <see cref="M:X.I2`1.M2(`0)"/>
        void M2(T p);

        /// <see cref="I2{T}.M3{U}(U)"/>
        /// <see cref="M:X.I2`1.M3``1(``0)"/>
        void M3<U>(U p);
    }
}
```
回复于 2024-04-19T16:22:14+08:00
2
进一步从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.
```
还将正确提供工具提示，而他们的版本使用花括号呈现它 .
回复于 2024-04-19T16:22:14+08:00

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

回复于 2024-04-19T16:22:14+08:00

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

回复于 2024-04-19T16:22:14+08:00

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

7 回答

TL; DR：

XML文档评论cref规则：

XML文档评论cref备忘单：

相关问题