コードドキュメントジェネレーター

これはコードからコードドキュメント(詳細設計書)を生成するツールです。

License

This project was released under the MIT License.

前提条件

1. Microsoft Windows
   • macOSのExcelではPowerShellからのオートメーションが現時点では利用不可能のためです。
   • ExcelはLinux版が現時点ではありません。
2. Java 11以降
3. PowerShell 7.x 以降
4. Microsoft Excel
   • 検証はしていませんが、xlsx形式が扱えれば大丈夫かと思われます。

概要

Javadocはインターフェース仕様をコメントとして記述できますが、 これは内部処理仕様をコメントとして記述できるようにしたものです。 (なお、インターフェース仕様については従来のJavadocを用います。)

次のようなソースコードファイルを詳細設計工程で用意します。 この時点では、内部処理を実際に記述する必要はありません。

上記のコードをツールに読み込ませ、出力されるドキュメントは以下のようなイメージになります。

出力されるドキュメントはテンプレートファイルがあり、それをカスタマイズすることで出力されるドキュメントの見た目の変更が可能です。

後は、実際に内部処理を追加してゆき、処理・仕様変更に伴い、 コメントを修正し、再生成を行うことで、常にドキュメントとソースコードと同期させることができます。

利用方法

アーカイブを展開すると、binディレクトリ下に実行スクリプトがあります。 このツールは2段階に分けて処理を行います。

1. コードパーサー(sharon.ps1)
   • Javaソースコードを解析し、コメントを抽出します。 抽出した情報をgananの入力情報となる独自形式のXMLとして出力します。

   & ./sharon.ps1 -Path [入力パス] --OutputDirectory [出力ディレクトリ]

   1. -Path [入力パス]
      • 解析対象となるJavaソースコードを指定します。
      • ディレクトリパス、.javaファイル自体を直接指定出来ます。
      • 複数指定することが可能です。
   2. -OutputDirectory [出力ディレクトリ]
      • XMLの出力先ディレクトリを指定します。
2. ドキュメント整形(ganan.ps1)
   • Excelのテンプレートファイルとsharonの出力したXMLを読み込み、 情報を埋め込んでExcelコードドキュメントを生成します。

   & ./ganan.ps1 -Path [入力ディレクトリ] -Template [テンプレートファイル] -OutputDirectory [出力ディレクトリ]

   1. -Path [入力ディレクトリ]
      • XMLの入力ディレクトリを指定します。
      • sharonで出力ディレクトリと指定したディレクトリを指定します。
   2. -Template [テンプレートファイル]
      • テンプレートとなるExcelファイルを指定します。
   3. -OutputDirectory [出力ディレクトリ]
      • 生成したExcelドキュメントを出力するディレクトリを指定します。