XMLコメントを使用して、クラスライブラリのすべてのタイプ、メソッド、プロパティなどを完全に文書化しようとしましたが、cref
属性(see
たとえば、タグで使用される)に関連する奇妙な効果に遭遇しました。このMSDNページのアドバイスに加えて、MSDNや他のWebサイトの他のさまざまな例に従うと、cref
タグを使用して参照値を指定するときは常に、参照を分類する特定のマーカー('など)をプレフィックスとして付ける必要があるようです。タイプの場合はT:'、メソッドの場合は' M:')。
ただし、Microsoft Sandcastleを使用すると、これらのプレフィックスを見逃すことにより、生成されたドキュメント(この場合はCHMヘルプファイル)に影響があることがわかりました。プレフィックスを含めると(私が信じるすべての状況で)、参照は太字のテキストとしてページにレンダリングされます...ただし、プレフィックスを除外すると、参照はAPIリファレンス内の適切なページへのアンカー(リンク)としてレンダリングされます。(すべて?)参照に接頭辞を付ける推奨される方法が最も役に立たない結果をもたらすことは私にはかなり奇妙に思えます-ある場合には参照を太字でレンダリングし、別の場合にはリンクする必要があるのはなぜですか?誰かがこれに光を当てることができれば幸いです。