XMLコメント - 参照が完全に資格を与えるのを見るべきですか？

StackOverflow https://stackoverflow.com/questions/5994551

質問

基本的に、完全修飾XMLを使用するのは本当に（まったく）必要なのはいつも必要です。 

<see cref="T:MyNamespace.Sub.MyType"/> //Option 1
<see cref="T:MyType"> //Option 2
.

また、.NET Frameworkオブジェクトへの参照についてはどうですか？ 

<see cref="T:System.Collections.Generic.ICollection{T}"/> //Option 1
<see cref="T:ICollection{T}"/> //Option 2
.

完全予選アイテムは常にMicrosoftのSandcastleが物事を正しくリンクできるようになることを理解していますが、すべてが完全に資格を与えるのに必要ですか？

SIDENOTE：Microsoft Sandcastleは.NET Frameworkヘルプファイルにリンクすることができますか、または<see cref="T:System.Collections.Generic.ICollection{T}"/>を参照して時間を無駄にしますか？

役に立ちましたか？

解決

両方とも joseph と Ben 便利なポイントをタッチしますが、最近だと思いますSandcastleの経験が役に立つかもしれません：

  1. プロジェクトをコンパイルすると、Visual Studioが警告を出すことで、参照が有効であるかどうかをすぐにお知らせします。これが独自のタイプへの参照であろうとするかどうかシステムの種類（およびVSはあなたの「使い方」ステートメントを尊重します）。

  2. システムタイプをマスキングするシナリオでは、検討するケースが2つあります。あなたのシグニチャはあなたのタイプ（上記の（1）でカバーされている）またはあなたのシグネチャにシステムタイプを正確に複製します。後者の場合は、名前を完全に修飾することによって明示的な曖昧さを必要とします。

  3. メンバータイプの接頭辞（例： "t：superwidget"）を明示的に指定することで触れましたが、これはほとんどの人が実現するよりも重要です。メンバータイプを使用している場合プレフィックスは、完全修飾名が必須です。これは実際にMSDNに記載されていますが、 eerm> fine print - XMLファイルの処理。そして、問題を悪化させるために、完全修飾名を省略した場合は、ビルドタイムで警告が登録されます（！）。最後のSandcastleレンダリングでは、単にリンクは生成されません。他の問題がありますが、メンバータイプのプレフィックスを明示的に指定した場合 - 実用的なSandcastleのヒントのマイ記事のセクション、 TAMING SAND CASTLE：あなたの文書化のための.NETプログラマーのガイドコード

他のヒント

Sandcastleのために話すことはできませんが、他の道具との私の経験に基づいています。再配置、範囲内でない場合はタイプを修飾する必要があると思われます。

つまり、using System.Collections.Genericの場合は、ICollection{T}を修飾する必要はありません。ただし、同じファイルに独自のICollection{T}インターフェイスを定義している場合は、が前者の資格を認めなければならない（後者と同様に考えてください）。

私の意見では、フレームワークの<see cref />-ingの時間を無駄にしていません。そのヘルプトピックに対して通話が行われたときに、Visual Studioヘルププロバイダーが実行時に傍受および解釈できるはずです。私は最近それを使っていませんでしたが、それは過去にかなりうまくいっていました。

完全予選に関してはほとんどのシナリオでは必要ありませんが、 BENがに記載されています。参照されているものが範囲内である限り（あなたがそれを参照している場合はあなたがそれを使用している場合はあなたがそれを使用している場合はあなたが完全に修飾された形式を使用していないように追加するべきです）。タイプだけで十分なはありません。

ライセンス： CC-BY-SA と 帰属
所属していません StackOverflow
scroll top