2009-04-22 11 views
2

XMLコメントを使用してクラスライブラリのすべての型、メソッド、プロパティなどを完全に文書化しようとしていますが、cref属性(seeタグ例えば)。 this MSDN pageのアドバイスと、MSDNや他のウェブサイトのさまざまな例を参考にして、crefタグを使って基準値を指定するときはいつも、それにrefresを分類する特定のマーカーを付ける必要があります: 'は型、' M: 'はメソッド)。.NET XMLドキュメントの参照接頭辞

しかし、Microsoft Sandcastleを使用すると、これらの接頭辞を紛失すると、生成されたドキュメント(この場合はCHMヘルプファイル)に影響があることがわかりました。接頭辞を含めて(私が納得するすべての状況で)、参照は太字のテキストとしてページに表示されます...しかし、接頭辞は、API参照内の適切なページへのアンカー(リンク)としてレンダリングされます。接頭辞(すべて?)の接頭辞の推奨される方法が最も有用でない結果をもたらしていること、なぜリファレンスがあるケースで太字で表示され、別のケースでリンクされるべきなのか、私は誰かがこれについていくつかの光を当てることができれば感謝します。

答えて

2

これは、あなたが砂の城のどのバージョンを使用しているbug in sandcastle

されているように見えますか?

recent discussionsは、少なくともシステムタイプでは、その回答で提示された例がT:とM:全体を落としてしまったので、実際には修飾名の使用を避けることが示唆されていますまたは珍しい。

This documentationは、どのタイプ/メソッド/定数を指し示すことができるかをコンパイラが指摘できることを強く暗示しています。あなたはxmlでこれを確認しましたか?

+0

ああ、良い見つける。しかし、それはおそらく修正されていることは奇妙です。私はSandcastleの最新バージョン(2008年5月)をhttp://sandcastlestyles.codeplex.com/のパッチと共に使用しています。 – Noldorin

+0

実際には、コンパイラが自動的に接頭辞を追加するように見えます(参照名を完全に修飾するだけでなく)。私はもう少しテストをしましたが、接頭辞を含めると型名を完全に修飾しなければならないか、または参照が意味をなさないという問題があるようでした。結論として、すべてのケースでコード内にプレフィックスを使用することは避けられます。 (私が間違っていれば私を訂正してください)とにかく、お返事ありがとう! – Noldorin

+0

私は、特定の注釈付きフォームを使用する必要がある唯一の時間は、名前の衝突がある場合です( クラスBar:ICloneable {public object Clone; object ICloneable.Clone(){}} 私はこれを頻繁に使用する必要はないと思います。 – ShuggyCoUk