24

基本的に、完全修飾xmlを使用することが本当に必要なのはいつですか（あるとしても）。リファレンスを参照してください。

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

また、.NETFrameworkオブジェクトへの参照についてはどうでしょうか。

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

完全に適格なアイテムは常にMicrosoftのSandcastleが物事を適切にリンクできるようになることを理解していますが、すべてが完全に適格である必要がありますか？

補足：MicrosoftSandcastleは.NETFrameworkヘルプファイルにリンクできますか、それとも参照して時間を無駄にしています<see cref="T:System.Collections.Generic.ICollection{T}"/>か？

4

3 に答える 3

16

ジョセフとベンの両方が有用な点に触れていますが、私の最近のサンドキャッスルの経験は役立つかもしれないと思います：

  1. プロジェクトをコンパイルすると、Visual Studioは通常、ドキュメントコメント内の参照を解決できない場合に警告を発行して、参照が有効かどうかをすぐに通知します。これは、独自のタイプまたはシステムタイプへの参照です（VSは「使用する」ステートメントを尊重します）。

  2. ローカルタイプがシステムタイプをマスキングするシナリオでは、考慮すべき2つのケースがあります。署名がタイプを一意に修飾するか（上記（1）でカバー）、署名がシステムタイプを正確に複製します。後者の場合は、名前を完全に修飾することにより、明示的な曖昧性解消が必要です。

  3. メンバータイププレフィックス（「T：SuperWidget」など）を明示的に指定する方法に触れましたが、これはほとんどの人が理解しているよりも重要です。メンバータイププレフィックスを使用する場合は、完全修飾名が必要です。これは実際にはMSDNに文書化されていますが、非常に細かく印刷されています。 「XMLファイルの処理」を参照してください。さらに悪いことに、完全修飾名を省略しても、ビルド時に警告は表示されません（！）; 最終的なサンドキャッスルレンダリングでは、リンクは生成されません。メンバータイプのプレフィックスを明示的に指定すると、他にも問題が発生します。実際のサンドキャッスルのヒントに関する私の記事の「参照の曖昧性解消と解決」セクションを参照してください。Sandcastleを使いこなす：コードを文書化するための.NETプログラマーガイド。

于 2011-05-15T20:22:18.290 に答える
3

Sandcastleについて話すことはできませんが、ReSharperなどの他のツールでの経験に基づくと、a）スコープ内にない場合、またはb）より多くの別のタイプによってシャドウされている場合は、タイプを修飾する必要があるようです。ローカルで定義されます。

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

于 2011-05-13T17:24:01.073 に答える
3

<see cref />私の意見では、フレームワークの作成に時間を無駄にしているわけではありません。Visual Studioヘルププロバイダーは、そのヘルプトピックが呼び出されたときに、実行時にインターセプトして解釈できる必要があります。最近は使用していませんが、過去にはかなりうまく機能していました。

完全な資格については、ほとんどのシナリオでは必要ありませんが、ベンが述べたように、用途によって異なります。参照しているものがスコープ内にある限り（参照している場合はそれを使用する可能性が高いため、スコープ内にある必要があります。または、コードが完全修飾フォームを使用しないようにusingを追加する必要があります）。タイプだけで十分です。

于 2011-05-13T17:45:10.353 に答える