kazuk は null に触れてしまった

C# / .NET 系技術ネタ縛りでお送りしております

DocCodeMargeTool

 

DocCodeMargeTool は .NET Framework でのドキュメンテーションコメントを Markdown 風の軽いシンタックスで書く事ができるツールです。

Visual Studio Gallary からダウンロードできますし、機能拡張マネージャでも入ると思います。

image

インストールしてプロジェクトを作成、ないしは既存のプロジェクト配下の項目をソリューションエクスプローラーで選択し、「プロジェクト」メニューから「Enable Document Marge」を行うと、ソリューションにビルド用の targets ファイルと、dll が追加され、プロジェクトにビルドアクションで DocumentPart が追加されます。

imageimage

プロジェクトの設定でXMLドキュメントコメントを生成するようにし、一回ビルドしておきましょう。(現在のビルド構成でのアセンブリが出力ディレクトリに無いと型名やメソッド名の解釈ができないのでカスタムツールが失敗します。)

image

テキストファイルを追加し、カスタムツールに DocumentMarkupGenerator を設定し、適当にドキュメントを入力して保存すると、テキストファイルのファイル名で拡張子 xml でドキュメンテーションコメントの形式で、XMLファイルが出力されます。(シンタックスは後述)

出力された xml のビルドアクションに DocumentPart を指定すると、ドキュメントコメントXMLに指定のXMLがマージされます。

image

 

ドキュメントシンタックス

* メソッド名やクラス名、または XML ドキュメントコメントでのメンバ名

member 要素に展開されます。メソッド名やクラス名を記述すると現在のアセンブリから該当する要素を検索します。

要素の末尾に method, property , field, event のメンバ種別を示す単語を置く事ができます。同様に class, interface, enum, delegate 等、型の種別を示す単語も認識されます。

これらの単語は取り去られてメンバ検索されるだけなので、X method と書いた場合に X がプロパティだった等の場合も別段にエラーとかは出ません。最終的には警告になる等を実装しようと思っています。

T: や M: 等ドキュメンテーションコメントXMLでのメンバIDを直接指定する事ができます。これらの指定を行った場合には、そのまま出力されます。

** summary や remarks 等のセクション名

XML ドキュメンテーションコメントの XML での member 配下の要素になります。メンバを指定したがセクションを指定していない状態でドキュメントを記述すると自動的に summary 配下の記述とされます。

remarks での特記事項や注意事項、 example に使用例等を記述します。

+ 番号付リスト

ドキュメンテーションコメントの番号付きリストが出力されます。(1. 項目, 2. 項目)

– 箇条書きリスト

同様に箇条書き記号付きのリストになります。(・ 項目, ・項目)

4文字以上のスペース コード

行頭に4文字以上のスペース、またはタブが記述された行はコード行になります。

その他のテキスト

ドキュメントの内容として、そのまま出力されます。

 

現状出力できない物

param 要素、exceptions 要素等は現状で出力する事はできません。パラメータの説明や例外の説明等はソース上にドキュメンテーションコメントである方がむしろ良いと思っているのであえてサポートしていません。 長くなりがちな remarks や、example 等をきっちり書きたいけどソースを汚したくないというニーズ向けの物で、ソース上に書いた方が良いものはソース上に書くべきだという立ち位置です。これらを出力できた方が良いという強い要望があれば検討はしようと思いますがドキュメンテーションコメントを代替し、ソース上でドキュメンテーションコメントをする事を否定するものでは無いためです。

仕様詳細

[Enable Document Marge] で行われる事

ソリューションディレクトリに .docmargebuild ディレクトリが存在しなければ作成し、DocumentMargeBuildTasks.dll および、DocumentMarge.targets を配置します。

csproj の末尾に、DocumentMarge.targets を Import する要素が無ければ作成し、存在すれば削除します。(Disable)

DocumentMarge.targets での定義

  1. DocumentMargeBuildTasks.dll をタスクアセンブリとして取りこみ
  2. DocumentPart ビルドアクション項目を宣言
  3. DocCodeMarge_MargeDocument ターゲットを宣言し、CoreCompile 後に割り込みします。

DocCodeMarge_MargeDocument は DocumentMargeBuildTasks.dll に実装された DocumentMarge タスクを実行しているだけです。

DocumentMarge MsBuild Task

以下の 3 パラメータで動作します。

  1. InputFiles 必須パラメータ、入力ファイルの項目配列です
  2. OutputFile 必須パラメータ、出力ファイルのパス名を指定します
  3. MargeExistingOutput 必須パラメータ、 true の場合には出力ファイルの位置に存在する(通常はC#コンパイラが作成した)ドキュメントコメントXML に InputFiles で指定されたファイルから各種要素を追加します。 false の場合には OutputFile で指定された位置のファイルは読み込みません。

ちょっと変わった使い方

オーバーロード等、summary,remarks, example を共有したい場合、ソース上でドキュメントコメントの include を使ってドキュメントを挿入できます。

<include> (C#)

DocumentMarkupGenerator で出力されたXMLはpathパラメータとして doc/members/member[@name=’ドキュメントメンバID’] で参照できますので、同一の remarksや example を出力したいメンバにそれぞれ include を記述する事でドキュメントをC#コンパイラに参照させることができます。元のXMLを最終出力に入れたくない場合には DocumentPart ビルドアクションを指定しなければそのようになります。

 

一応売り物です

1ライセンス 200~300円、一人一回買えば一生使えますという形にしたいなぁ等と考えてます。高い安い、機能不足、その他ご指摘あるかもしれませんが、嫁子供居る身でタダでくれてやるというほどの別収入があるわけでなしって事で。

Doc<Code> も合わせてどうぞ

ドキュメンテーションコメントでのドキュメントを見る側については Doc<Code> でサポートしています。こちらも有償ツールになりますがよろしくお願いします。 インストール方法等販売開始のお知らせ

コメントを残す

以下に詳細を記入するか、アイコンをクリックしてログインしてください。

WordPress.com ロゴ

WordPress.com アカウントを使ってコメントしています。 ログアウト / 変更 )

Twitter 画像

Twitter アカウントを使ってコメントしています。 ログアウト / 変更 )

Facebook の写真

Facebook アカウントを使ってコメントしています。 ログアウト / 変更 )

Google+ フォト

Google+ アカウントを使ってコメントしています。 ログアウト / 変更 )

%s と連携中

%d人のブロガーが「いいね」をつけました。