web-dev-qa-db-ja.com

XMLドキュメントでジェネリッククラスとメソッドを参照する方法

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参照を作成できますか？

c#genericsreferencexml-documentation
186
Svish

メソッドを参照するには：

/// <see cref="FancyClass{T}.FancyMethod{K}(T)"/> for more information.
244
Lasse Vågsæther Karlsen
/// <summary>Uses a <see cref="FancyClass{T}" /> instance.</summary>

ところで、それは 。Net Framework 2. および . のMSDNドキュメントにありましたが、 version 3.5 にはありませんでした。

43
thinkbeforecoding

これまでに示した答えはどれも、私にとって完全に機能しません。 ReSharperはseeタグをに変換しません Ctrl+クリック可能なリンク（例 image here ）完全に解決しない限り。

OPのメソッドがTestという名前空間にある場合、表示されるメソッドへの完全に解決されたリンクは次のようになります。

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

解決できる可能性があるため、クラス型パラメーターの数の前にバックティックが1つだけあり、メソッド型パラメーターの数の前に2つのバックティックがあります。その後、パラメーターは適切な数のバックティックを持つインデックスがゼロのパラメーターです。

したがって、FancyClassには1つのクラス型パラメーターがあり、FancyMethodには1つの型パラメーターがあり、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_である3​​つのタイプパラメータを持つメソッドを持つ2つのタイプパラメータを持つクラス」

追加のメモとして、私はこれがどこにも文書化されておらず、天才でもないことをコンパイラが私に言った。必要なのは、テストプロジェクト XMLドキュメントを有効にする を作成してから、リンクを作成するコードを挿入し、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ドキュメントには、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>
_
19
MrLore

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

canが署名にFancyClass<string>を含むメソッドを参照している間（たとえば、パラメーター型として）、cannotこのような閉じたジェネリック型を直接参照しています。 2番目の例はその制限を回避します。 （これは 静的System.String.Concat(IEnumerable<string>)メソッドのMSDNリファレンスページ で見られます）。 ：

XMLドキュメントコメントcrefルール：

  • {}山括弧ではなく、中括弧<>で汎用型パラメータリストを囲みます。これにより、後者を&lt;および&gt;としてエスケープする必要がなくなります。ドキュメントコメントはXMLであることに注意してください。

  • プレフィクス（タイプにはT:、メソッドにはM:、プロパティにはP:、フィールドにはF:など）を含めると、コンパイラは参照の検証を実行せず、単にcref属性値は、ドキュメンテーションXML出力に直接。このため、このようなファイルに適用される特別な "ID文字列"構文 を使用する必要があります。常に完全修飾識別子を使用し、バックティックを使用してジェネリック型パラメーターを参照します（型の`n、メソッドの``n）。

  • prefixを省略すると、通常の言語命名規則が適用されます。usingステートメントがある名前空間を削除でき、System.Int32の代わりにintなどの言語のタイプキーワードを使用できます。また、コンパイラは参照の正確性を確認します。

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);
    }
}
19
stakx

ラッセと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.

また、ツールチップは正しく提供されますが、バージョンでは中括弧で表示されます。

10
Stephen Drew
/// Here we discuss the use of <typeparamref name="TYourExcellentType"/>.
/// <typeparam name="TYourExcellentType">Your exellent documentation</typeparam>
4
JohnL4
/// <see cref="FancyClass&lt;T>.FancyMethod&lt;K>(T)"/> for more information.
1
Max Toro