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


198

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を見ることができますか?

回答:


257

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

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

3
その答えをありがとう!実際には<see>のMSDNのページにありません:msdn.microsoft.com/en-us/library/acd0tfbe.aspx
joce

6
実際には、VS2010のツールチップでも機能するため、一般的な引数の数を示す必要があると考えています。たとえば、「FancyClass 1{T}.FancyMethod1 {K}(T)」
Stephen Drew

どういう意味かわからない。私はそれらを追加する必要がありませんでした、そしてそれはいつも私のために働きました。それが機能しない具体的な例はありますか?もしそうなら、それをどこかに投稿してください(または自分で答えを提供してください。)
Lasse V. Karlsen '26 / 10/26

@ラッセ、スティーブの回答と以下のコメントをご覧ください。あなたの答えは正しいIntellisenseツールチップをカバーしていません。
Jakub Januszkiewicz 2012

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

ところで、それは.Net Framework 2.0および3.0のMSDNドキュメントに存在していましたが、バージョン3.5では姿を消しました


4
Tの特定のインスタンスはどうですか?文字列のように?できませんか?
Svish

どういう意味ですか?特定のバージョンを宣言できないため、それを参照することもできません。
Lasse V. Karlsen、

たとえばメソッドが、たとえばList <string>のみを返す場合。しかし、重要ではありません:)
Svish

7
はい、私も不思議に思っていました... FancyClass {string}を書き込むときはSquigglesを再シャープしますが、FancyClass {String}を書き込むときはそうではありません...
thinkbeforecoding

6
上記の「コーディング前に考える」による観察の理由は、c#エイリアスでは機能しないためです。たとえば、あなたが使用する必要があるInt32の代わりにintSingle代わりにfloatなど(この上の場合、誰つまずくここで、この情報を置く)
AnorZaken

27

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>(例えば、パラメータの種類など)を、あなたがすることはできません直接、このようなクローズジェネリック型を参照します。2番目の例は、その制限を回避します。(これは、静的System.String.Concat(IEnumerable<string>)メソッドのMSDNリファレンスページなどで見られます)。:

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

  • 汎用型パラメーターリストを{}<>かっこの代わりに中かっこで囲みます。このスペアは、あなたは、後者逃げる&lt;&gt;-覚えているが、ドキュメンテーションコメントはXMLです!

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

  • 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);
    }
}

そのT部分だけを参照する方法は?
nawfal 2018年

4
<typeparamref name="T"/>
考え出し

21

これまでに示した答えのどれも、私にとって完全に機能しません。ReSharperは、完全に解決されない限り、seeタグをCtrl+クリック可能なリンク(例:)に変換しません画像はこちら

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

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

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

したがってFancyClass、1つのクラス型パラメーターとFancyMethod1つの型パラメーターがあり、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)

または「メソッドのパラメータは、3つの型パラメータを持つメソッドを持つ2種類のパラメータを持つクラスClassType1ClassType2MethodType1MethodType2MethodType3


追加のメモとして、このドキュメントはどこにも記載されておらず、私は天才ではありません。コンパイラーがすべてを教えてくれました。テストプロジェクトを作成し、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>

3
これは、特に試行錯誤を繰り返さなくても正しい表記法を見つけるトリックのために、より多くの賛成票を獲得するはずです。私の男を称賛
ピーター

10

ラッセとTBCの回答からさらに:

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

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

ツールチップも正しく表示されますが、バージョンは中括弧でレンダリングされます。


2
使い方<CREFを参照してください= "System.Collections.Generic.List 1{T}"/>** causes a build-time warning: **XML comment on 'Blah' has syntactically incorrect cref attribute 'System.Collections.Generic.List1 <T> ?あなたは1がこれを使用する方法について詳しく説明する気だろう-
ヤクブJanuszkiewicz

2
こんにちはJakubさん、これは実際に機能していないようです。ツールチップを正しく機能させる唯一の方法は、<see cref = "T:<fullTypeName>` 1 {T} "/>を使用することです。
Stephen Drew

2
はい、部分的に取得しました。メソッド自体がジェネリックでない場合(List <T> .Add()など)、これは機能します:<see cref = "M:System.Collections.Generic.List`1 {T} .Add(T)" /> 。
Jakub Januszkiewicz

1
うまくいかないようです。私が書いた一般的な拡張メソッド(ArrayListをList <T>に変換)のコメントヘッダーに<see cref = "M:System.Collections.Generic.List`1 {T}" />がありますが、ReSharperがフラグを立てます構文エラーとして、IntelliSenseはそれをそのまま表示します。2010 VS / R#6.1.37.86
マイクLoux

8
ああ!<see cref = "T:System.Collections.Generic.List`1" /> "を機能させることができました。したがって、中括弧の代わりにT:を使用するとうまくいきました。名前空間全体が展開されます。名前空間を含めないとトリックは機能しないため、完全ではありませんが、機能します
Mike Loux

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

3
他の回答はジェネリッククラスを参照する方法をカバーしていることに注意してください。この回答は、型パラメーターをそれ自体で参照する方法を示しています。
jrh

弊社のサイトを使用することにより、あなたは弊社のクッキーポリシーおよびプライバシーポリシーを読み、理解したものとみなされます。
Licensed under cc by-sa 3.0 with attribution required.