Ktouth Brand. on Web

け〜くんこと K.Ktouth のだらだらした日常と突発的に作るプログラムや読み物とかの雑多サイト



[2013年07月21日]

添付プロパティのドキュメントはどう書く?

2013年07月21日 22:23更新 筆者:K.Ktouth

先日の続き

添付プロパティのテストコードやら実装やらがうまく行ったので、次にヘルプドキュメントの作成をしたんです。
SandCastle や SHFB の使い方はいろんな所で解説されているので置いておいて、気になったのが「添付プロパティと名前空間の説明欄が空欄になっている」事です。

まぁ、要するに名前空間と添付プロパティにはコード実体が無いため、XMLコメントをつけることが出来ないんですね。一応名前空間の方には

using System.Runtime.CompilerServices;
namespace FooBar {
  /// <summary>適当な名前空間の概要</summary>
  [CompilerGenerated]
  internal class NamespaceDoc { }
}

と言う風に特殊な名前のクラスを準備してやれば定義できますが、余計な情報が埋め込まれてしまうという問題もありますし。

んで、一番簡単なのは「自動生成に頼らず自前でドキュメントを追加する」事です(笑)
そらまぁ全部を自前で核には大変すぎるからこその自動生成ですが、添付プロパティと名前空間だけなら数個から多くても数十個だけ、しかも大概は <summary> 要素だけあれば済むわけで。
細かい書き方は以下のページを参照して書いてみました。

添付プロパティも「P:KtouthBrand.WPF.TrimPath.Source」のようにシンプルに書くだけです。

もっとも外部ファイルになってしまうので、ライブラリを使用する際のインテリセンスでコメントが出て来ないという問題もあります。
そこで適当な「アセンブリのXMLドキュメントに該当部分を合成する」だけの簡単なツールを作ってビルド後に実行することで対応。まー、開発者が自分で使うだけなんで本気で最低限の実装のみしかしてません(笑)

これで何故かリンクが張られない部分もうまく行くかな……と思ったら、添付プロパティへのリンクが張られてない…… orz
何処間違えてるんだろ?
# 説明部分は当然うまく行ってるんだけど……???

本日のリンク元
その他のリンク元
検索