さて、ただいま病人は戦力外です<おい といっても職場は暇どころか戦場真っ只中なわけで……、なので、このタイミングで開発ドキュメントを整備してしまおうなんて事を考えたところ、ふと、気がつきました。もはや凄まじい数のクラスメソッドプロパティ、こんなのWordやExcelになんてやってらんない。そこでMSDNみたくHelpファイルにしちまえ、てなわけで砂の城プロジェクトが始動したわけです。
SandCalstleセットアップ
まずは、SandCastle をダウンロードします。msiファイルで配布されているのでサクっとインストールしてしまいましょう。次にHelpファイル作成のためのキットもセットします。 こちらのページの下の方に「日本語版Zipファイル」があるのでこれをダウンロードして解凍します。パスはそのまま変更せずにただの「Unzip」で大丈夫ですよん。
SandCasle
http://www.microsoft.com/downloads/details.aspx?FamilyId=E82EA71D-DA89-42EE-A715-696E3A4873B2&displaylang=en
HelpKit
http://msdn2.microsoft.com/en-us/library/ms669985.aspx
まぁ後はCUIでさくーっとやっちゃえば良いんですが、世間じゃGUIが主流らしいんです。で、GUIなツールをさらに……って事でSandCastle Help File Builder も入れちゃいます。
SandCastle Help File Builder
http://www.codeplex.com/SHFB
HELPファイル作成準備開始
後は、HELPファイルに記述する中身の整備。実はこれが一番大変だったりする。今からのプロジェクトで使う場合にこれを使うなら、はじめからコーディング規約とかにしとくと良いかも。みんなが幸せになれるから。とりあえず、ソースファイルにシングルコーテーションを3つ入れると、こんな風になるんで
''' <summary> ''' ここがタイトル、簡潔かつ美しくビシッと決めるw ''' </summary> ''' <param name="hoge">パラメータの説明も入れとくとGood</param> ''' <remarks>オブジェクトの説明とか書くとかっこいい</remarks> |
以下、コメントをちまちまと入れておく。C#だと「///」ですかね。クラスやメソッドやプロパティや関数、それもPublicだのProtectedだのだのだのだの……きーっ!となりたいけど我慢して、がんばれ、後が楽になる&かっこええ!と浸れるからっって自分を信じてっ(笑)。 ちなみに、こんなタグなんかが使えるみたいです。他にも、<TABLE>タグが使えるのも確認済。ハッシュテーブルのキーValue一覧とかに使えるんじゃないかと(つか、使ったんだけどね)
タグ |
説明 |
<summary> |
概要 |
<remarks> |
解説 |
<param> |
メソッドの引数 |
<returns> |
メソッドの戻り値 |
<value> |
プロパティ |
<see> |
クラスやメンバへのリンク |
<example> |
サンプル・コード |
<seealso> |
クラスやメンバへの参照 |
このあたりのタグをできるだけ使って書いておくと素敵♪
できたらプロジェクトのプロパティにあるコンパイルタグの「xmlドキュメント生成」へチェックをして、いざリビルド!
完成した、exe(dll)と一緒のフォルダにxmlがあることが確認できれば準備完了です。ちなみに、このXMLファイルに後からごにょごにょと追記してもっともっとときめき!なコンテンツにすることも可能。
SandCastle Help File Builder 起動
まずは、新規プロジェクトを作成。ADDボタンを押下して作成したいexe,dllファイルを指定すると、同パス同名のXMLファイルも同時に取得して設定してくれます。
で、プロパティに色々とセット。
言語は日本語が選べるので、こちらを選択しておくこと。
ヘルプファイルのOUTPUTパスも指定。こうしておかないとどこに出来たかわかんなくなる。
設定したら、ビルド開始。延々延々とビルド終了を待ちます。
ビルド終了したら、OUTPUTパスにCHMファイルがあるのを確認。
かっけーっ!すっごいすっごいヘルプファイルの完成!!
出来上がったヘルプファイルはいじるにいじって、悦に浸れます。いやまぢで。