Understand APIを使用したドキュメント生成

はじめに

ソフトウェアを開発、アップデートを続けていくうえでネックになるのが仕様書の更新ではないでしょうか？ソフトの改修に時間をとられ、仕様書の更新が間に合わないといった声をよく耳にします。あとから書くにしても、ソースを読み解くのも一苦労だと思います。

Understand APIは、Understandが解析したデータをPythonスクリプトを使用して自由に抽出することができます。（※使用には「Understand フローティング with API」ライセンスが必要です）この機能を利用することで、完成したコードから仕様書を作成することもできてしまいます。
今回は簡単な関数仕様書を作成するスクリプトを作成してみました。

準備

Understandのインストール

Understandのインストールが必要です。今回は日本語最新版のUnderstand 7.0（Windows版）をインストールしました。（今回ご紹介するスクリプトはUnderstand 6.3以降であれば動作します）

出力内容の決定

準備段階として、仕様書に何を出力するかを決める必要があります。Understandの情報ブラウザーを確認し、抽出できる情報から以下の情報を出力することにしました。

• 関数名
• 引数
• 戻り値
• ローカル変数
• 関数の定義ファイル名
• 説明（関数上部に書かれているコメント）
• アノテーション（Understandで関数に対して付与しているコメント）

また、関数のフロー図を付けることにより、視覚的にも関数の動作が分かるようにしました。

まずはUnderstandデータベースをオープンしてインスタンスを取得する必要があります。通常、サンプルのように引数からプロジェクトファイルパスを取得します。

db = understand.open(args[1])

作成されたインスタンス「db」を使用して、Understandデータベースを操作します。

関数一覧の取得

データベースのインスタンスには、自動的にファイルや関数、変数の一覧を取得してくれる関数「ents」があります。これを使用して簡単に関数の一覧「funcs」を取得します。

funcs = db.ents("Function ~unknown ~unresolved")

引数にはフィルター条件となる文字列を指定しますが、スペースで区切ることで複数指定することができます。

• エンティティの種類：File, Class, Function, Method, Global Objectなど。Understandのエンティティフィルターの名前を参考にしてください。
• ~unknown ~unresolved: チルダは除外するための指定子です。Understand上で解析不能なもの（Unknown Function）などを除外します。解析結果が良好な関数のみ取得したい、という場合に付与します。

関数のデータ抽出

ents関数にて抽出した関数一覧の１つ１つは「Ent」クラスとなります。関数、変数などエンティティの種類にかかわらず、すべて「Ent」クラスとなります。Entクラスには数多くの関数が存在し、名前やタイプ、コメントなどが格納されています。今回のサンプルでは、表示に必要な部分を抽出します。

• 関数名：ent.name()
• 引数：ent.parameters(true)
• 戻り値：ent.type()
• ローカル変数：ent.ents(“”, “Local Object”)
• 定義ファイル名：ent.ref(“definedin”).ent().longname()　※
• コメント：ent.comments()
• アノテーション：ent.annotations()

※定義元ファイルは参照エンティティとして格納されていますので、参照先のエンティティの名前を取得しています。

コントロールフロー図の出力

グラフの出力は簡単です。ent.draw()関数を使用することで、Understandで表示しているグラフを画像やマークアップ言語で出力することができます。
今回はマークダウンでドキュメントを作成するため、軽量マークアップ言語の.dot形式を選択しています。

func.draw("Control Flow", dotFilePath, "Cluster=on", "Classic")

• 第一引数：グラフ名を指定します。コントロールフロー図は”Control Flow”です。
• 第二引数：出力するファイルパスです。ファイル名に.dot拡張子を付けることで、Dotファイルとして出力します。
• 第三引数：グラフの表示オプションをセミコロンで区切って指定します。Understand GUI上で表示されるオプション名を指定できます。（例）Cluster=on;Layout=Horizontal;Comments=off
• 第四引数：グラフの類別を指定します。

スクリプトの実行

実際にスクリプトを実行します。
実行にはupython.exeを使用します。中身はPythonですが、Understandモジュールを自動的に解決してくれます。

upython genFunctionDocument.py myProject.und ./output

通常のPythonコマンドも使用できますが、その際はunderstandモジュールを正しくインポートする必要があります。
参考FAQ：FAQ (最新バージョン) | ソースコード解析ツール Understand | テクマトリックス株式会社

出力結果

出力結果は画像のようなマークダウン形式となります。

フロー図もすべてテキストのため、非常にサイズの小さいドキュメントが生成できました。

表示方法

このままでは見づらいため、閲覧するときにはツールを使って変換する必要があります。
VSCodeにもレンダリングツールがあります。今回は「Markdown Preview Enhanced」を使用しました。こちらのツールはマークダウンを表示するツールとなっていて、Dot形式のグラフ表示にも対応しています。

表示した結果がこちら（画像が長くなってしまったので、２つに分けて表示しています）

まとめ

いかがでしたでしょうか？一度スクリプトを作成してしまえば、またソフト改修がおこなわれてもコマンド１つで簡単に最新の関数仕様書を作成することができます。スクリプト実行をソフト改修時のワークフローに入れておけば、仕様書が古くなることも回避できると思います。

今回ご紹介したサンプルスクリプトをベースに、ご自身にあった形へと改修してもらえれば幸いです。