C#にはドキュメントコメントがあります。
特定のコードブロックの直前にXMLタグを記述することで、
コードのドキュメントを作成できるというものです。
(詳細はXMLドキュメント コメント(C# プログラミング ガイド)を参照のこと)
このドキュメントコメント、今までコーディング規約やC#標準ということで使ってきたけど、
ふと思い起こしてみると一度もドキュメント作成で使ったことがない。。。
そこで、ドキュメントコメントが実際にどんな感じのドキュメントになるのか実践してみました。
1.XMLドキュメントファイルを作成する。
ドキュメントを作成するには、まずドキュメントコメントからXMLドキュメントファイルを
作成する必要があります。方法は簡単で、
- VisualStudioの場合
プロジェクトのプロパティで、ビルドタブの"XMLドキュメントファイル"の
チェックをONにしてビルド。
チェックをONにしてビルド。
- コマンドラインでコンパイルする場合
/doc:ファイル名のコンパイラオプションを使用。
これだけです。これでXMLドキュメントファイルが指定した場所に出力されます。
1で作成したXMLドキュメントファイルですが、単なるXMLファイルです。
これをちゃんとしたドキュメントにするには、NDocやSandcastleといった
ドキュメント作成ツールを使います。今回はSandcastle Help File Builderを使って
ドキュメントを作成しようと思います。
Sandcastle Help File BuilderはCodePlexからダウンロードできます。
http://shfb.codeplex.com/
DOWNLOADSからSandcastle Help File Builder Installerをダウンロードしてください。
ダウンロードしたSHFBGuidedInstaller_***.zipを解凍したフォルダに、
SandcastleInstaller.exeがあるのでこれを実行。
あとはウィザードに従って必要なものをインストールします。
インストールは下記のブログが参考になります。
http://d.hatena.ne.jp/tueda_wolf/20120717/p3
3.Sandcastle Help File Builderでドキュメントを作成する。
インストールが完了したら、スタートメニューのすべてのプログラム-Sandcastle Help File Builderから
Sandcastle Help File Builder GUIを起動します。
起動したら、画面右側にあるProject Exploreにドキュメントを作成するexeファイルと
XMLドキュメントファイルを追加します。
Project Explore - Documentation Sourcesの右クリックメニュー[Add Documentation Source...]を
選択すると、ファイル選択ダイアログが開くので、対象のexeファイルを選択してください。
※XMLドキュメントファイルとexeファイルの拡張子以外の部分が同じなら、exeファイルを追加するだけで
XMLドキュメントファイルも自動で追加されます。追加されない場合は、同じ方法でXMLドキュメントファイルも追加します。
次に画面左側のProject Propertiesで出力方法等の各種設定を行います。
| プロパティ | 説明 |
|---|---|
| Build | |
| BuildAssemblerVerbosity | ビルドログの詳細度を設定。 |
| BuildLogFile | ビルドログファイルを設定。 指定無しの場合、OutputPaehで指定したフォルダにLastBuild.logが作成される。 |
| CleanIntermediates | trueならビルド成功時に中間ファイルを削除する。 |
| ComponentConfigurations | ビルドコンポーネントを設定。 Cached～を追加するとビルド時間を短く出来たりする。 |
| CppCommentsFixup | C++コンパイラは特定の状況で非標準のXMLコメントが生成することがあり、C++のメソッドのドキュメント化に失敗することがある。そのような場合、ここをtrueにすればドキュメント化可能になる場合がある。 |
| DisableCodeBlockComponent | trueなら<code>タグで囲まれた部分のコードに対する色付けが無くなる。 |
| FrameworkVersion | 対象の.NET Framework versionを設定。 |
| HelpFileFormat | ドキュメントの出力形式を設定。選択したすべての形式で出力される。 |
| IndentHtml | デバッグ用のプロパティ。通常はfalseで問題なし。 |
| KeepLogFile | trueならビルド成功後もlogファイルを削除しない。falseなら削除する。 |
| PlugInConfigurations | ビルドプロセスプラグインを設定。 |
| UserDefinedProperties | MSBuildのプロジェクトプロパティを追加する。 |
| Help File | |
| ContentPlacement | ???(調べたんですが分かりませんでした...) |
| CopyrightHref | "コピーライト"リンクのリンク先URL。 |
| CopyrightText | "コピーライト"リンクに表示される文字列。 |
| FeedbackEMailAddress | "フィードバックの送信"リンクのE-Mailアドレス。 |
| FeedbackEMailLinkText | "フィードバックの送信"リンクに表示される文字列。 |
| FooterText | ドキュメントの各ページに表示するフッター文字列。 |
| HeaderText | ドキュメントの各ページに表示するフッター文字列。 |
| HelpTitle | HelpFileのTitleを設定。 |
| HtmlHelpName | コンパイルされたHtmlヘルプファイルにつけられる名前。 HtmlHelp1で出力すると[名前].chmでヘルプファイルが作成される。 |
| Language | HelpFileBuilderによって挿入される文字列の言語を設定。 |
| NamingMethod | Help-htmlフォルダに作成されるファイル等の命名方法を設定。 |
| Preliminary | trueならページヘッダーに仮のドキュメントであるという警告を出す。 Languageが日本語の場合、"[これは仮のドキュメントであり、予告なく変更されます。]"が表示される。 |
| PresentationStyle | 生成されるページの外観を設定。 |
| RootNamespaceContainer | trueならルート名前空間のページが生成される。 |
| RootNamespaceTitle | ルート名前空間の名前を設定。 |
| SdkLinkTarget | MSDNのLinkをクリックしたときのリンク先の開き方を設定。 HTML Help1、MS Help 2、MS Help Viewerのプロパティ-SDKLinkTypeがMsdnの場合のみ、このプロパティは有効となる。 |
| SyntaxFilters | Syntax欄に表示するプログラミング言語を設定。 |
| そのほかの重要なプロパティ | |
| OutputPath | 生成されたHelpFileの出力先パスを設定。 |
| Show Missing Tagsの各プロパティ | ドキュメントコメントでタグが抜けている場合、抜けているタグのドキュメント出力位置にデフォルトのメッセージを表示するかどうかを設定。 |
| Visibilityの各プロパティ | ドキュメント化する対象を設定。 |
デフォルトの設定でもいいのですが、HelpFileFormat、Language、PresentationStyleあたりは
ちゃんと設定した方がいいと思います。
設定が完了したら、いよいよドキュメントを作成します。
メニューの[Documentation]-[Build Project]でビルドを実行します。
Build Outputウィンドウに"Build completed successfully at..."が出力されれば作成成功です。
Project PropertiesのOutputPathで設定した場所にMSDNチックなドキュメントが
作成されているのが確認できると思います。
今回はとりあえずここまで。
次回のエントリーでは、実際のドキュメントコメントとドキュメントの対応について書こうと思います。
0 件のコメント:
コメントを投稿