如何在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>

顺便说一句,它出现在.Net Framework 2.0和3.0的MSDN文档中,但它在版本3.5中消失了

Answer 3

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>(例如,作为参数类型),则不能直接引用这样的封闭的通用类型.第二个例子解决了这个限制.(例如,在静态System.String.Concat(IEnumerable<string>)方法的MSDN refence页面上可以看到这一点).:

XML文档注释cref规则:

• 用大括号括起泛型类型参数列表{}而不是<>尖括号.这使您免于逃避后者,<并且>- 记住,文档注释是XML!

• 如果包含前缀(例如,T:对于类型,M:对于方法,P:对于属性,F:对于字段),编译器将不会对引用执行任何验证,而只是将cref属性值直接复制到文档XML输出.因此,您必须使用适用于此类文件的特殊"ID字符串"语法:始终使用完全限定标识符,并使用反引号来引用泛型类型参数(`n类型,``n方法).

• 如果省略前缀,则应用常规语言命名规则:您可以删除具有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);
    }
}

Answer 4

到目前为止,所有答案都没有完全适用于我.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)

或"具有两个类型参数,其具有带有三个类型参数其中该方法的参数是方法类ClassType1,ClassType2,MethodType1,MethodType2,MethodType3"

作为一个补充说明,我没有发现任何记录,我不是一个天才,编译告诉我这一切.您所要做的就是创建一个测试项目,启用XML文档,然后插入您想要编写链接的代码,并在其上放置XML doc注释(///):

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- > member元素中的链接name:

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

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

Answer 5

进一步从Lasse和TBC的答案:

/// <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>