• Imagix 4D ユーザガイド
  • 目次

ドキュメントの作成

Imagix 4D に搭載のドキュメント生成機能では、ツールのデータベースに格納された情報を活用し、詳細なドキュメントを自動的に作成することが可能です。ドキュメントの範囲とフォーマットを設定することにより、さまざまな状況に適したドキュメントを作成できます。その一般的な用途は、次の通りです。

包括的な設計用ドキュメント: 自身で作成したコードや人から引き継いだコードなど、ソフトウェアにおける特定の側面を参照し調査をする上で最善の方法となるのは、多くの場合、Imagix 4D のユーザ・インターフェイスを使用することです。ただし、予算的な問題、技術的な制約、変更があまり発生しない設計関連の成果物が要求されるなど、この方法が適切ではないケースがあります。そのような場合には、プロジェクト全体をカバーするドキュメントによって、組込みの遷移機能と一部の基本的な解析機能をともなう、総合的な設計情報が提供されます。

コードレビュー用ドキュメント: Imagix 4D によって生成されたドキュメントを、体系的なコードレビュー用のプラットフォームとして使用することが可能です。ファイル、クラス、シンボルのレベルで、レビュー対象のコード単位について、広範囲にわたり詳細な解析が記載されたドキュメントを自動的に作成することができます。またコンテンツとレイアウトを制御することによって、ユーザ標準のレビュープロセスにドキュメントを簡単に適合させることができます。

変更の影響または問題の解析用ドキュメント: Imagix 4D を使用してソフトウェアの制御フローや依存関係における問題を調査すると同時に、情報のやりとりや参照を目的に調査結果を記録する必要が生じるケースがあります。このような操作も、Imagix 4D のユーザ・インターフェイスの [ブックマーク] 機能を活用して、実現することができます。一方で、外部ドキュメントを入手する必要がある場合には、ドキュメント機能を利用することで、包括的な記録を迅速かつ自動的に生成することが可能です。

ドキュメントの範囲

[ドキュメント化] ダイアログでは、ソフトウェアに関してドキュメント化したい部分や、そのドキュメントに記載したい情報の種類を指定します。Imagix 4D は、自身のデータベース上のデータとソースファイルに存在するデータを組み合わせ、自動的にドキュメントを生成します。

ドキュメントの範囲はドキュメント機能を起動した場所によって、ある程度、制御されます。[ドキュメント化] ダイアログは、ユーザ・インターフェイスの大半の場所から開くことが可能ですが、起動した場所により、異なる範囲の選択項目が提示されます。

プロジェクトを全体的にドキュメント化するには、メインのメニューバーから [ドキュメント化] ダイアログを開きます。例えばコードレビュー用のドキュメントなど、特定のファイルまたはクラスに関するドキュメントを作成する場合は、ユーザ・インターフェイスの任意の場所で、該当のファイルまたはクラスを右クリックします。コンテキスト・センシティブメニューが表示されるので、そこで [ドキュメント化ト...]アクションを選択してください。[グラフ] ウィンドウを使用して作業を行っている際に、ドキュメント化する必要のある関数依存関係の呼び出しグラフを作成した場合には、その [グラフ] ウィンドウのローカルメニューバーからダイアログを起動します。

ドキュメントのフォーマット

[ドキュメント化] 機能は、さまざまな用途に対応するよう ASCII、RTF、HTML の3つのフォーマットで出力を生成します。どのドキュメントも、この3種類のフォーマットで適切に作成することが可能ですが、各フォーマットには、それぞれに適した利用方法があります。多くの場合、ドキュメントの用途に応じて、選択すべきフォーマットが決まります。

ASCII フォーマットでは、シンプルで読み易いファイルが生成されます。Imagix 4D から情報をエクスポートする迅速な方法の1つに、ASCII ドキュメントを生成し後処理することがあげられます。本ツールは強力な解析機能とエクスポート機能を備えた大規模なデータベースを搭載しているため、より高度なデータのエクスポートやカスタムレポートが必要な場合は、Imagix 社または各地域の代理店に、ご連絡ください。

RTF（リッチテキストフォーマット）では、ハードコピーのドキュメントを生成することができます。Imagix 4D で（一連の）ファイルを作成し、これをワードプロセッサにインポートすることも可能です。サイズの大きいドキュメントは、ワードプロセッサのツールを利用することで、文字の書式やページレイアウトを変更できます。また、ワードプロセッサで目次を作成する場合は、目次に適用する書式として [セクション] および [サブセクション] を使用してください。ただし、RTF は通常、比較的に小規模なコードレビューや、問題解析を目的とするドキュメントに適したフォーマットです。そのようなドキュメントには、目次を必要としないケースが多く存在します。さらにワードプロセッサを用いることで、記述したい任意の注釈を迅速に追加し、その後で作業中のタスクを共有できる書類や電子文書を生成することが可能です。

HTML フォーマットは、詳細なインデックス付きのオンライン・ドキュメントを作成することができます。グラフ内に表示されるシンボルを含め、すべてのシンボル参照がリンクされます。さらにメトリクス表とクラスの階層構造も対象となります。このフォーマットは一般的に、包括的な設計文書に適しています。

ドキュメントのコンテンツとレイアウト

プロジェクトのスコープ内において、ドキュメントに出力するコンテンツを幅広く調整することができます。インクルードするシンボル型や、インクルード対象の各シンボル型について生成される情報を指定することが可能です。Imagix 4D の使用に際し、この調整を行う場合には [ドキュメント設定] ダイアログを利用することが、最も簡単な方法となります。このダイアログにはタブを使用した一連のチェックボックスがあり、インクルードするメトリクスや、検索するコメント形式などを指定することができます。

特定のシンボル型に対する利用可能な情報の定義と、その情報の表示順序は、../imagix/user/user_doc.txt テンプレートで設定します。上級ユーザにおいては、用途に合わせて出力を最適化するために、このファイルの内容を確認の上、修正を加える必要が生じるケースがあります。このような場合には、そのファイル自体に設定方法の記載がありますので適宜、参照してください。また、その際は必ずオリジナル・ファイルのコピーを作成してから、変更を行ってください。

[ドキュメント設定] ダイアログおよび user_doc.txt テンプレートの代わりに、DocGen シートを利用することもできます。DocGen シートを用いることで、ダイアログやテンプレートの場合と同じ内容を指定したのち、それらの設定をセッション間で保存することが可能です。さらに、このシートはドキュメントおよび、そのビルド処理に関して、さらに多くの要素を制御することができます。例えば、ページの幅やグラフのサイズなどの外観的な要素から、ドキュメントが分散して生成されるビルド上の問題に至るまで、幅広く対応しています。

../imagix/user/doc_gen ディレクトリにある .dgn ファイルはすべて、[ドキュメント] ダイアログを使用して適用することができます。サンプルの DocGen シート（../imagix/user/doc_gen/sample.dg_）には、本シートのあらゆる設定に関する情報が記載されています。

一連の DocGen シートを構成することにより、容易に適用できるドキュメント形式の定義を特定のドキュメントタイプで生成するよう、それぞれ最適化した上で作成することが可能です。