ソフトウェアの色々な機能を作るための部品となるライブラリ。それらを初めてを使うときに頼りになるのが利用例、サンプルコードと呼ばれるものです。StackOverflow などの Q&A サイトでも、「〇〇を使って××するにはどうしたらいいか」という質問がよく行われています。
最近はオープンソースソフトウェアとして多数のプロジェクトのソースコードが公開されているのだから、そこからうまくクラスごとの利用例を収集できるのでは?と考えて、NAIST ソフトウェア工学研究室とオーストラリア・ウロンゴン大学の研究チームで協力してツールを作ってみました。
開発したツール Catalogen は、Java を対象として、クラス名を引数に、利用例のリストを HTML 形式で出力します。Apache POI という Microsoft Office のデータファイルを読み書きするライブラリのうち、XSSFWorkbook という Excel ファイルを扱うためのクラスの利用例を対象とした実行結果の例が こちら(XSSFWorkbook | Catalogen) です。
このツールは、以下のような仕組みで動作しています(著者最終版原稿PDFはこちら)。
- オープンソースソフトウェアのソースコードを検索するサービス Searchcode.com に接続し、クラス名をクエリとして渡し、そのクラス名を使っているソースファイルを集めます。
- 集めたソースファイルの中から、クラス名と変数名が連続しているところを見つけます。これが利用例の開始位置となります。
- 開始位置から、その変数名が出現する行だけを拾い集めます。これが利用例の本体となります。
- 同じ変数名が他の用途にも何度も使われる可能性があるので、"}" で変数のスコープが無効になったところで探索を終了し、見つかった行の範囲を利用例とします。
- 利用例それぞれに対して、Natural Machine Translation 技術で Java のメソッド → Javadoc コメントの対応関係を学習したモデルを適用し、内容を表現しそうなコメントを割り当てます。
- 利用例のうち、似ているもの同士をクラスタリングして、各クラスタから一番短いもの(最も単純そうなもの)を代表として、HTML に出力します。その他の利用例は、クラスタ名をクリックしたときだけ表示されるものとして扱います。
Apache POI の各クラスに対する実行結果はこちらにああります。コメントの内容等にはまだまだ改善の余地はありますが、全自動でこれだけ情報を整理できることに可能性を感じていただければ幸いです。本ツールは、ドキュメンテーション生成技術に関するワークショップ Dysdoc3 の一部として開催された DOCGEN CHALLENGE 2018 において、Usefulness 部門第2位に選ばれました。
このツールのようなドキュメント生成技術は、「ドキュメントを書いても誰も読まない、すぐに古くなってしまう」という問題に対して、「ドキュメントは必要なときに、その人の知識に合わせて作ればよい」という考えから、ここ数年、研究者が活発に議論を交わしているトピックの1つです。今後も、新しいアイディアや技術に基づいたツールが登場することになると思います。