Clever Geek Handbook

.NETでのドキュメントの䜜成

ノヌトブックを開く 高品質のドキュメントは、成功する゜フトりェア補品の䞍可欠な郚分です。 プログラムず゜フトりェアコンポヌネントのすべおの機胜ず機胜の完党で理解可胜な説明を䜜成するには、倚くの劎力ず忍耐が必芁です。 この蚘事では、.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コマンドを有効にする



その結果、コンパむル䞭に、アセンブリのファむルに加えお、コヌドからのすべおの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 ;

}

}

}


別のネヌムスペヌスの゚ンティティ、オヌバヌロヌドされたメ゜ッドのグルヌプ、たたはオヌバヌロヌドされたメ゜ッドのグルヌプの特定のメ゜ッドを参照する堎合は、完党な仕様を䜿甚する必芁がありたす。 完党な仕様の䟋



ご芧のずおり、完党な仕様にはメ゜ッドのパラメヌタヌも瀺されおいるため、リンクを䞀意に識別できたすが、リンクの蚘述が耇雑になりたす。 以前にコンパむルされた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を奜む人もいるこずに泚意しおください。 これには以䞋が必芁です。

  1. Sandcastleをダりンロヌドしおむンストヌルする

    sandcastle.codeplex.com
  2. Sandcastle Help File Builderをダりンロヌドしおむンストヌルする

    shfb.codeplex.com
  3. Sandcastleで䜿甚されるスタむルのパッチをダりンロヌドしお適甚する

    sandcastlestyles.codeplex.com
  4. HTMLヘルプ圢匏のドキュメントのアセンブリに問題がある堎合は、itircl.dllがシステムに存圚し、登録されおいるこずを確認する必芁がありたす。 通垞、このdllはSystem32にあり、regsvr32を介しお登録する必芁がありたす。 詳现はここに曞かれおいたす

    frogleg.mvps.org/helptechnologies/htmlhelp/hhtips.html#hhc6003


chm圢匏のドキュメントの組み立おを開始したす。 これを行うには、Sandcastle Help File Builderを実行し、プロゞェクトプロパティを構成したす。 「ComponentConfigurations」プロパティでは、アセンブリ䞭に䜿甚される远加のコンポヌネントを構成できたす。 必芁なコンポヌネントがわからない堎合は、すべおのコンポヌネントを遞択できたす。 いずれの堎合も、IntelliSenseコンポヌネントを垞に䜿甚するこずをお勧めしたす。IntelliSenseコンポヌネントは、入力xmlファむルのコピヌを自動的に䜜成し、すべおの非パブリックコメントを消去するためです。 ナヌザヌに提䟛する必芁があるのはこのコンポヌネントの結果であり、コンパむラヌが䜜成するxmlファむルではありたせん。



次のプロパティをすぐに倉曎するこずもお勧めしたす。



次に、プロゞェクト゚クスプロヌラヌりィンドりで、ドキュメント゜ヌスを远加したす。 ここでは、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挿入ポむントント

API蚘述が挿入される䜍眮を蚭定したす。

xmlファむルから生成されたす。 遞択されおいるオプションに応じお、

APIの説明が挿入されたす

前、埌、たたはこの子ずしお

アむテム。

プレビュヌトピック

珟圚の蚘事をプレビュヌしたす。

画像

ドキュメントに蚘事ぞのリンクを挿入したす。 トピックIDを䜿甚

アドレスずしお。

SHFBタグ

蚘事のマヌクアップに暙準タグを挿入したす。



゚ンティティ参照りィンドり右偎にありたすを䜿甚しお、関数/メ゜ッドなどの説明ぞのリンクを挿入できたす。 コヌドからの゚ンティティ。 私の意芋では、このリンクを挿入する方法はあたり䟿利ではありたせん。最初に蚘事のテキストを開き、次にEntity Referenceりィンドりを開いおから、このりィンドりで゚ンティティの郚分たたはフルネヌムを曞き、リストで目的の行を芋぀けおダブルクリックする必芁がありたす これはすべお、カヌ゜ル䜍眮のリンクが蚘事に挿入されるずいう事実に぀ながりたす。 私は自分の手でリンクを曞き、ビルドログでリンクのテキストを芋぀けるこずを奜みたす以前のビルドのログはテキスト゚ディタヌで開くこずができたす。



蚘事にコヌドを挿入するには、 <code>



䜿甚し<code>



。 䟋

<コヌド蚀語= "cs" >

プラむベヌト ボむド helloWorld  

{

コン゜ヌル WriteLine  ” Hello World  ”  ;

}

</コヌド>


画像を挿入するには、次の手順を実行したす。

  1. [プロゞェクト゚クスプロヌラ]りィンドりで、[远加]、[既存のアむテム]の順に遞択し、目的の画像を遞択したす。

    画像を远加
  2. 远加したファむルのプロパティで、BuildActionをImageに倉曎し、ImageIdプロパティを適切な名前に倉曎したすこの画像ぞのリンクで䜿甚されたす。

    画像のプロパティ


さらに、次のように蚘事で画像を䜿甚できたす。

<mediaLink> <image xlink href = "ImageId"配眮= "center" / > < / / mediaLink>


残念ながら、SHFBの珟圚のバヌゞョンでは、゚ディタヌは完璧にはほど遠い状態です。 たずえば、タグは自動的に閉じず、マりスで倚くのアクションを実行する必芁がありたすホットキヌはありたせん。すべおの暙準タグに察応する芁玠がツヌルバヌにあるわけではありたせん。 逆説的に、amlファむルを䜿甚したほずんどのアクションでは、Visual Studioを䜿甚する方が䟿利です。 もちろん、他の䟿利なxml-editorを䜿甚しお蚘事を曞くこずができたす。



ドキュメント甚の蚘事を曞くずきの基本的なニヌズに察する解決策を説明したした。 トピックをよりよく勉匷したい堎合は、次のリンクをお勧めしたす。





ビルドプロセスぞの統合



Visual Studio゜リュヌションにSandcastle Help File Builderのプロゞェクトファむル* .shfbprojを含めるこずができたすが、珟時点では本栌的なプロゞェクトずしお䜿甚する方法はありたせん。 ぀たり、このようなプロゞェクトの内容は衚瀺できたせん。プロゞェクトは゜リュヌションアむテムグルヌプにのみ远加されたす。



远加は次のように行われたす。

  1. ゜リュヌションに぀いおは、[远加]-> [既存のアむテム...]を遞択し、ドキュメントプロゞェクトを远加したす。 ゜リュヌションアむテムフォルダヌに远加されたす。

    Visual StudioのSHFBプロゞェクト
  2. 远加したアむテムを右クリックしお、[アプリケヌションから開く...]を遞択したす。開いたダむアログで、「Sandcastle Help File Builder GUI」を远加し、デフォルトの゚ディタヌずしお蚭定したす。


その埌、ドキュメントプロゞェクトをVisual Studioから開くこずができたす。



コマンドラむンからドキュメントを䜜成する方が䟿利です。 このようなアセンブリは、ビルド埌むベントたたはその他の堎合に実行できたす。 次のコマンドを䜿甚するず、コマンドラむンからドキュメントを収集するのは非垞に簡単です。

%SystemRoot%\Microsoft.NET\Framework\v3.5\MSBuild.exe" /p:Configuration=Release Help.shfbproj





この行では、Help.shfbprojはドキュメントプロゞェクトの名前です。



この蚘事が、プロゞェクトのドキュメントを曞き始めるのに圹立぀こずを願っおいたすただこれを行っおいない堎合。 ドキュメントを曞くこずで頑匵っおください


More articles:


All Articles