高品質のドキュメントは、成功するソフトウェア製品の不可欠な部分です。 プログラムとソフトウェアコンポーネントのすべての機能と機能の完全で理解可能な説明を作成するには、多くの労力と忍耐が必要です。 この記事では、.NETコンポーネントのドキュメント作成の実用的な側面について説明します。
開発者向けの.NETライブラリが用意されているか、ほぼ準備ができていると仮定します（エンドユーザーでもあります）。 ライブラリAPIは申し分なく、バグの数は驚くほど少なく、実際にはライブラリではなく、単なる完璧なコードの保管庫です。 ポイントは小さい-ユーザーにこのすばらしい製品を使用する方法を説明することです。
ドキュメントを書くためのさまざまなアプローチがあります。 一部のチームは、製品作成の開始時にドキュメントの作成を開始することを好みます。 他の人は、作業を完了するためにマニュアルの作成を延期しています。 一部のチームでは、開発者から開発者へ、そしてマネージャーからマネージャーへと行く特別な人々がドキュメントを作成し、製品に関する知識を蓄積しています。 多くの小さなチームにはそのような特別な人がいないため、多くの場合、ドキュメントは開発者によって作成されます。 誰かがHelp＆Manualなどのサードパーティツールを使用します。このツールでは、実際のテキストエディターのように、非常に複雑なレイアウトを作成し、出力でさまざまな形式のドキュメントを取得できます。 多くの人々は、最近広く推進されている異なるアプローチを使用します。プログラム/ライブラリコードで直接ドキュメントを記述します。
私の仕事では、サードパーティのツールと組み込みのツールの両方を使用しました。 彼はすぐにそして最後の瞬間にドキュメントを書き始めました。 その結果、完成に近づき、API、機能セットなどが完成するほど、製品の作成の後半にドキュメントを書き始める方が良いと自分で決めました。つまり、ドキュメントの調整頻度は少なくなります。 コードで直接ドキュメントを書くことは、最終的にはサードパーティのプログラムよりも便利であることが判明しましたが、最初はまったく逆のように見えました。 この記事では、コードで直接ドキュメントを書く方法について説明します。
APIについて説明します
コンパイラC＃およびVB.NETは、特別な方法でフォーマットされたコメント（xmlコメント）を認識し、必要に応じて、ドキュメントの作成に使用できるxmlファイルを作成できます。 この機会を利用するには、xmlコメントを使用してすべてのパブリッククラスとメソッドを記述する必要があります。 次のようになります。
/// <summary>
///によって返されるABGR値からRコンポーネントを取得します
/// <cref = "O：BitMiracle.LibTiff.Classic.Tiff.ReadRGBAImage"> ReadRGBAImage </ see>を参照してください。
/// </ summary>
/// <param name = "abgr"> ABGR値</ param>
/// <returns> ABGR値からのRコンポーネント</ returns>
public static int GetR （ int abgr ）
{
return （ abgr ＆ 0xff ） ;
}
デフォルトでは、コメントからのxmlファイルの作成は無効になっています。 [ビルド]タブのプロジェクトプロパティで有効にする必要があります。
その結果、コンパイル中に、アセンブリのファイルに加えて、コードからのすべてのxml-comments（非パブリック構造に関するコメントを含む）を含むxml-fileが生成されます。 このファイル自体は、アセンブリ（dll）の隣に配置すると、ユーザーがコードを入力したときにVisual StudioのIntelliSense関数でメソッドの説明を表示できるという点で便利です。 次に、上記のGetR関数を検索する方法の例を示します。
ただし、ほとんどの場合、生成されたxmlファイルには、ユーザーが必要としない、または表示できない内部構造に関するコメントが含まれています。 以下に、パブリックメソッドの説明のみが含まれるようにxmlファイルを自動的にクリアする方法を記述します。
すべてのxmlタグを詳細に検討するのではなく、最も一般的に使用されるタグについて簡単に説明してみます。
サマリータグは、クラス、インターフェイス、列挙、クラスまたはインターフェイスのメソッドとプロパティ、および列挙メンバーの目的を簡単に説明するために使用されます。
paramタグを使用すると、関数で受け入れられるパラメーターを記述できます。 このタグは、受け入れられた各パラメーターに使用する必要があります。 関数の戻り値を記述するために、
returnsタグが使用されます。
値タグは、いくつかのプロパティを取得または返す値を記述するのに役立ちます。 ある意味では、値タグは返品タグに類似しています。
/// <summary>
///フォントの上昇を取得します。
/// </ summary>
/// <value>フォントの上昇</ value>
/// <注釈>上昇は、到達したベースラインからの最大の高さです
///このフォントのグリフにより、グリフの高さを除く
///アクセント記号付き文字</ remarks>
パブリック ショートアセント
{
得る
{
Implを返します。 上昇
}
}
非常に便利な（そして、残念ながら、しばしば無視される）
remarksタグは、記述されたエンティティのメモを指定できるようにします。 このタグは、列挙のメンバーの説明を除き、ほぼどこでも使用できます。 実際、列挙メンバーも使用できますが、vs2005のスタイルで発行されたドキュメントでは、これらのメモは単に表示されず、そのようなメモの有用性が低下します。
さらに実用的なメモ/推奨事項をいくつか示します。
GhostDocというVisual Studioの拡張機能をダウンロードしてインストールします。 この拡張機能は、すべてのスタジオバージョン（バージョン2005以降）で機能し、xmlコメントの作成を大幅に簡素化します。 Ctrl-Shift-Dを押すと、この拡張機能はカーソルが現在置かれているエンティティの説明を挿入します。 必要なすべてのタグが挿入され、たとえば、メソッドの名前とそのパラメーターの名前に基づいて説明テキストが生成されます。 多くの場合、生成されたテキストを調整および補足するためだけに残ります。
コードに直接ドキュメントを書くことの欠点は、コードよりもコメントが多い場合があり、コードの読み取りが非常に困難になる場合があることです。 この問題を回避するには、パブリックインターフェイスと実装を完全に分離することが非常に便利です。
オーバーロードされたメソッドが複数ある場合、それらのドキュメントを生成するときに別のページが作成されます（そのようなページの
例を次に示します）。 このページのテキストは、オーバーロードメソッドのいずれかの説明のオーバーロードタグで指定する必要があります。
/// <summary>
///フォントバイトを指定されたストリームに保存します。
/// </ summary>
/// <param name = "stream">フォントバイトを保存するストリーム</ param>
/// <overloads>フォントバイトをファイルまたはストリームに保存します。
public void Save （ Stream stream ）
{
Impl。 保存 （ストリーム） ;
}
別のメソッドへの参照を与えたり、あるメソッドの説明を入力したい場合は、
<see cref="X:MEMBER"> </see>ような構造を使用する必要があります。Xはエンティティのタイプを示すオプションのプレフィックスです（クラスのT 、Mはメソッド、Pはプロパティ、Oはオーバーロードされたメソッドのグループ）、およびMEMBERはエンティティの完全または部分的な指定です。 たとえば、同じクラスの2つのメソッド間または同じ名前空間の2つのエンティティ間のリンクに、部分的な指定と欠落しているプレフィックスを使用できます。
部分的な仕様の使用例（PdfFontEmbedStyleはPdfFontと同じ名前空間にあります）：
公開 シール クラス PdfFont
{
...
/// <summary>
///を指定する<see cref = "PdfFontEmbedStyle" />値を取得または設定します
///このフォントがどのようにドキュメントに埋め込まれるか。
/// </ summary>
/// <value> <see cref = "PdfFontEmbedStyle" />を指定する値
///このフォントがドキュメントにどのように埋め込まれるか</ value>
public PdfFontEmbedStyle EmbedStyle
{
得る
{
Implを返します。 EmbedStyle
}
セット
{
Impl。 EmbedStyle = value ;
}
}
}
別のネームスペースのエンティティ、オーバーロードされたメソッドのグループ、またはオーバーロードされたメソッドのグループの特定のメソッドを参照する場合は、完全な仕様を使用する必要があります。 完全な仕様の例：
- プロパティ参照
<see cref="P:System.Exception.HResult"/> - メソッドリファレンス
<see cref="M:BitMiracle.LibTiff.Classic.Tiff.GetR(System.Int32)"/> - オーバーロードされたメソッドのグループへのリンク
<see cref="O:BitMiracle.LibTiff.Classic.Tiff.PrintDirectory"/> - クラス参照
<see cref="T:BitMiracle.LibTiff.Classic.TiffTagMethods"/>
ご覧のとおり、完全な仕様にはメソッドのパラメーターも示されているため、リンクを一意に識別できますが、リンクの記述が複雑になります。 以前にコンパイルされたxmlファイルから完全な仕様をコピーすることにより、手作業を節約できます。
オーバーロードされたメソッドのグループへのリンクでは、1つの迷惑が関連付けられます。 Visual Studioでは、このようなリンクを
O:XXX.YYYする必要がありますが、Sandcastle Help File Builderでは、そのようなリンクを
Overload:XXX.YYYする必要があります。 この問題を解決するには、ビルド後のイベントで呼び出され、xmlファイルの
O:を
Overload:に置き換える簡単なスクリプトを使用します。
ドキュメントの外部記事（APIの説明とは無関係）またはインターネット上のリソースにリンクするには、古くなった
<a>タグとhref属性を使用します。 たとえば、
<a href = "54cbd23d-dc55-44b9-921f-3a06efc2f6ce.htm"> </a>または
<a href = "http://site.com/page.html"> </a> 。 最初の例では、外部記事を含むドキュメントの名前は「TOPIC_ID.htm」という形式で表示されます。 トピックIDについては後で説明します。
次の記事のxmlコメントを使用して、コードのドキュメント化について詳しく読むことができます。
ドキュメントファイルを生成する
コンポーネントのxml記述が準備できたら、ドキュメントファイルを生成できます。 これには、Sandcastle + Sandcastle Help File Builder（SHFB）バンドルを使用することを好みます。 DocProjectを好む人もいることに注意してください。 これには以下が必要です。
- Sandcastleをダウンロードしてインストールする
sandcastle.codeplex.com - Sandcastle Help File Builderをダウンロードしてインストールする
shfb.codeplex.com - Sandcastleで使用されるスタイルのパッチをダウンロードして適用する
sandcastlestyles.codeplex.com - HTMLヘルプ形式のドキュメントのアセンブリに問題がある場合は、itircl.dllがシステムに存在し、登録されていることを確認する必要があります。 通常、このdllはSystem32にあり、regsvr32を介して登録する必要があります。 詳細はここに書かれています：
frogleg.mvps.org/helptechnologies/htmlhelp/hhtips.html#hhc6003
chm形式のドキュメントの組み立てを開始します。 これを行うには、Sandcastle Help File Builderを実行し、プロジェクトプロパティを構成します。 「ComponentConfigurations」プロパティでは、アセンブリ中に使用される追加のコンポーネントを構成できます。 必要なコンポーネントがわからない場合は、すべてのコンポーネントを選択できます。 いずれの場合も、IntelliSenseコンポーネントを常に使用することをお勧めします。IntelliSenseコンポーネントは、入力xmlファイルのコピーを自動的に作成し、すべての非パブリックコメントを消去するためです。 ユーザーに提供する必要があるのはこのコンポーネントの結果であり、コンパイラーが作成するxmlファイルではありません。
次のプロパティをすぐに変更することもお勧めします。
- ビルドセクション：FrameworkVersion
- ヘルプファイルセクション：CopyrightHref、CopyrightText、FeedbackEMailAddress、FeedbackEMailLinkText、HelpTitle、HtmlHelpName
- セクションパス：OutputPath
次に、プロジェクトエクスプローラーウィンドウで、ドキュメントソースを追加します。 ここでは、C＃/ VB.NETプロジェクトファイルではなく、特定のアセンブリおよびコメント付きのxmlファイルを選択することをお勧めします。 プロジェクトファイルを選択すると、xmlコメントの変更がドキュメントに反映されないという問題が発生する場合があります。 誰がこれを責めるのか、私にはわかりません。
もう1つの重要な手順は、SHFBで名前空間を記述することです。 コード内のXMLコメントは名前空間に対して機能しないため、これを手動で行う必要があります。 コメントセクションとその中のNamespaceSummariesプロパティはここで役立ちます。 名前空間の説明では、標準のhtmlタグを使用できます。
プロジェクトのセットアップが完了しました。今度は.hmファイルをビルドします。 [ドキュメント]-> [プロジェクトのビルド]を選択します。すべてが正しく行われた場合、MSDNのスタイルで美しいドキュメントファイルが取得されます。
トピックに関する役立つリンク：
記事を書く
ただし、そこで停止しないでください。コンポーネントの単一のAPI記述では、完全なドキュメントを作成するには不十分です。 通常、優れたドキュメントには、追加の記事、例、FAQなどが含まれています。
[プロジェクトエクスプローラ]ウィンドウで、新しいコンテンツレイアウト要素を追加します。これは、ドキュメントに含まれる内容の説明です（相対位置を示します）。 [コンテンツレイアウト]ウィンドウに新しいトピックが追加されます。 各記事はMAML形式（.amlファイル）で記述されており、xmlベースの形式です。 Sandcastle Help File Builderには事前定義されたテンプレートのセットが付属しており、記事を書く際のデビューを大幅に簡素化します。 私は主に
概念テンプレートを使用しますが、あまり一般的ではありません。
各記事の説明は、一意の識別子であるトピックIDで始まります。 この識別子に基づいて、後でchmに入るhtmlファイルが生成されます。 生成されたhtmlファイルには、「TOPIC_ID.htm」という形式で名前が付けられます。 このトピックIDは、他の記事からの記事またはコード内のxmlコメントへのリンクにも使用されます。
記事を作成する場合、「TOPIC_ID.aml」という名前のファイルに保存することをお勧めします。 作成時に、ファイルの通常の名前をすぐに示すことができます。
記事を編集するときに役立つSHFBのコントロールのいくつかを検討してください。
| ドキュメントの開始ページを設定します（表示されるのは
ドキュメントを開く。
|
| API記述が挿入される位置を設定します。
xmlファイルから生成されます。 選択されているオプションに応じて、
APIの説明が挿入されます
前、後、またはこの子として
アイテム。
|
| 現在の記事をプレビューします。
|
| ドキュメントに記事へのリンクを挿入します。 トピックIDを使用
アドレスとして。
|
| 記事のマークアップに標準タグを挿入します。
|
エンティティ参照ウィンドウ（右側にあります）を使用して、関数/メソッドなどの説明へのリンクを挿入できます。 コードからのエンティティ。 私の意見では、このリンクを挿入する方法はあまり便利ではありません。最初に記事のテキストを開き、次にEntity Referenceウィンドウを開いてから、このウィンドウでエンティティの部分またはフルネームを書き、リストで目的の行を見つけてダブルクリックする必要があります これはすべて、カーソル位置のリンクが記事に挿入されるという事実につながります。 私は自分の手でリンクを書き、ビルドログでリンクのテキストを見つけることを好みます（以前のビルドのログはテキストエディターで開くことができます）。
記事にコードを挿入するには、
<code>使用し
<code> 。 例：
<コード言語= "cs" >
プライベート ボイド helloWorld （ ）
{
コンソール WriteLine （ ” Hello World ！ ” ） ;
}
</コード>
画像を挿入するには、次の手順を実行します。
- [プロジェクトエクスプローラ]ウィンドウで、[追加]、[既存のアイテム]の順に選択し、目的の画像を選択します。
- 追加したファイルのプロパティで、BuildActionをImageに変更し、ImageIdプロパティを適切な名前に変更します（この画像へのリンクで使用されます）。
さらに、次のように記事で画像を使用できます。
<mediaLink> <image xlink： href = "ImageId"配置= "center" / > < / / mediaLink>
残念ながら、SHFBの現在のバージョンでは、エディターは完璧にはほど遠い状態です。 たとえば、タグは自動的に閉じず、マウスで多くのアクションを実行する必要があります（ホットキーはありません）。すべての標準タグに対応する要素がツールバーにあるわけではありません。 逆説的に、amlファイルを使用したほとんどのアクションでは、Visual Studioを使用する方が便利です。 もちろん、他の便利なxml-editorを使用して記事を書くことができます。
ドキュメント用の記事を書くときの基本的なニーズに対する解決策を説明しました。 トピックをよりよく勉強したい場合は、次のリンクをお勧めします。
ビルドプロセスへの統合
Visual StudioソリューションにSandcastle Help File Builderのプロジェクトファイル（* .shfbproj）を含めることができますが、現時点では本格的なプロジェクトとして使用する方法はありません。 つまり、このようなプロジェクトの内容は表示できません。プロジェクトはソリューションアイテムグループにのみ追加されます。
追加は次のように行われます。
- ソリューションについては、[追加]-> [既存のアイテム...]を選択し、ドキュメントプロジェクトを追加します。 ソリューションアイテムフォルダーに追加されます。
- 追加したアイテムを右クリックして、[アプリケーションから開く...]を選択します。開いたダイアログで、「Sandcastle Help File Builder GUI」を追加し、デフォルトのエディターとして設定します。
その後、ドキュメントプロジェクトをVisual Studioから開くことができます。
コマンドラインからドキュメントを作成する方が便利です。 このようなアセンブリは、ビルド後イベントまたはその他の場合に実行できます。 次のコマンドを使用すると、コマンドラインからドキュメントを収集するのは非常に簡単です。
%SystemRoot%\Microsoft.NET\Framework\v3.5\MSBuild.exe" /p:Configuration=Release Help.shfbprojこの行では、Help.shfbprojはドキュメントプロジェクトの名前です。
この記事が、プロジェクトのドキュメントを書き始めるのに役立つことを願っています（まだこれを行っていない場合）。 ドキュメントを書くことで頑張ってください！