Comments
Description
Transcript
RDocを用いた数値モデルのドキュメント生成
情報の広場 ： （RDoc；Fortran；ドキュメント生成；数値モデル；Ruby) RDoc を用いた数値モデルのドキュメント生成 森 川 靖 小 大 ・石 高 正 渡 正 樹 ・堀之内 嗣 ・林 １．はじめに 祥 武 介 ドキュメント作成の手間を軽減し，ドキュメント整 この小論では，Fortran 90/95で書かれた数値モデ 備を促進させる手法は，ソースコードのコメント行に ルに付随するドキュメント生成とその管理の為になさ ドキュメント用の文書を埋め込むことによってモデル れてきた試みについて紹介し，オブジェクト指向スク とドキュメントの一元管理を実現し，かつ，ドキュメ リプト言語 Rubyによるドキュメント生成用のライブ ント生成をソースコード解析用のソフトウェアによっ ラリ RDoc を用いた手法について解説を行なう． て自動化することである．例えば，まつもとゆきひろ 数値モデルの開発や保守において，モデルを構成す 氏を中心に開発されたオブジェクト指向スクリプト言 るサブルーチンや関数など，プログラム単位の機能や 語 Ruby 1や，サン・マイクロシステムズ社により開 用法の詳細を記述したドキュメント（リファレンス 発 さ れ た オ ブ ジェク ト 指 向 プ ロ グ ラ ミ ン グ 言 語 マニュアル）の整備を行うことは必須な作業である． Java 2では，それぞれ RDoc 3，Javadoc 4といったド 数値モデルを利用する第三者にとっても，モデルを理 キュメント自動生成用のライブラリが用意されてい 解し，あるいはこれに改良を加える上で，このような る．C，C＋＋，Python，IDL に関しては Doxygen 5 ドキュメントが提供されていることは望ましい． というドキュメント生成用ソフトウェアが存在する． しかし，モデルの開発に合わせて常に最新のドキュ こ れ ら RDoc や Javadoc，Doxygen は，単 に ソース メントを整備しておくことは大変に手間のかかる作業 コードの解析やコメント行中に記述される文書の抜粋 である．その主な原因は，モデルで記述した内容とほ を行なうだけではなく，自動生成される HTML ド ぼ同じ内容（サブルーチンの名前や引数など）を再度 キュメントにハイパーリンクや見出し，箇条書きと ドキュメントとしても記述せねばならない点にある． ドキュメントとモデルとを別々のファイルで管理する 1 場合にはこの作業はさらに煩雑となる．そのためド 「オブジェクト指向スクリプト 言 語 Ruby」http:// キュメントの整備はついついおろそかになり，結果と www.ruby-lang.org/．近年，Rubyは地球科学にお けるデータ解析，可視化，数値シミュレーションに してモデル本体の開発にも支障をきたすこととなる． 対しても活用されている．その例については， 電脳 Rubyプ ロ ジェク ト」http://ruby.gfd-dennou.org/ を参照されたい．＜URL 参照日付2007/01/18＞ Document generation for numerical models by RDoc. Yasuhiro M ORIKAWA, 北海道大学理学院． morikawa＠gfd-dennou.org 2 3 M asaki ISHIWATARI, 北海道大学地球環境科学研 究院． Takeshi HORINOUCHI, 京都大学生存圏研究所． M asatsugu ODAKA,Yoshi-Yuki HAYASHI,北海 4 道大学理学院． 5 Ⓒ 2007 日本気象学会 2007年 2月 「サ ン・マ イ ク ロ シ ス テ ム ズ-Java テ ク ノ ロ ジ」 http://jp.sun.com/java/＜参照2007/01/18＞ 「RDoc：Ruby Standard Library Documentation」 http://www.ruby-doc.org/stdlib/libdoc/rdoc/ rdoc/＜参照2007/01/18＞ 「Javadoc Tool Home Page」http://java.sun.com/ j2se/javadoc/＜参照2007/01/18＞ 「Doxygen」http://www.doxygen.jp/＜参 照2007/ 01/18＞ 77 186 RDoc を用いた数値モデルのドキュメント生成 いった構造を付与することで，見やすく いやすいド に，参照するモジュールへのハイパーリンクの作成， キュメントの提供を可能としている．また，ソース サブルーチンや関数の引数のデータ型，INTENT 属 コードの可読性を低下させないよう，文書に構造を付 性（授 受 特 性)，引 数 キーワード（例： “call date 与するためのタグも簡素なものとなっている．上記以 ）も and time（values＝input)”に お け る“values” 外にも同種のライブラリやソフトウェアは数多く存在 自動的にドキュメントに反映する．しかし，コメント しており，現在この手法はリファレンスマニュアル管 に記述される内容は HTM L へ変換されても，ハイ 理の主流となりつつある． パーリンクや見出しや箇条書きといった構造を持たな これまでに気象学 野の数値モデルに用いられてき い文書となるため，リファレンスマニュアルとしては た 主 要 な 言 語 は Fortran 系 の 言 語 で あ り，近 年 は 不 である．他にも，Fortran 90/95の新機能である Fortran 90/95が主流である．Rubyによるドキュメ 多重定義を ント生成ライブラリ RDoc は，Rubyのみならず C や などの問題がある． 用したプログラムが正しく解析されない Fortran 90/95のソースコードを解析してドキュメン f90tohtml 8は，オクラホマ大学気象学講座の Brian トを生成することも可能である．しかし残念ながら Fiedler 氏ほかによって作成 さ れ た，Fortran 90/95 RDoc の Fortran 90/95解析機能には不十 ソースコードを HTML へ変換する Perl スクリプト な点が多 く，実用には耐えなかった．そこで我々はこの不十 である．このソフトウェアは大規模な数値モデルの な点を解決するべく，Fortran 90/95解析機能の改良， ソースコードを閲覧することを目的に開発され，現在 強 化 を 行 なった．以 下 で は，RDoc 以 外 の Fortran は ARPS，WRF，CAM において利用されている． 90/95プログラムのドキュメント生成方法について紹 f90tohtml は，USE 文中のモ ジュール 名 や CALL 文 介した後に，RDoc の特徴，および我々が施した改良 中のサブルーチン名を，該当するモジュールまたはサ 点について解説を行う．そして，この「RDoc For- ブルーチンのソースコードへのハイパーリンクに変換 tran 90/95ソース コード 解 析 機 能 強 化 版」(以 下， する．利用者はソースコードをブラウザで閲覧でき， RDoc 強化版）を用いたドキュメント生成の方法を実 プログラムが参照している別のモジュールやサブルー 例を チンへはハイパーリンクによって移動できる．しかし えて紹介する．ここで紹介する RDoc 強化版 はインターネット上に 開されており，現在その改良 ながら，このソフトウェアはサブルーチンや関数など 点がオリジナルの RDoc ライブラリ 3に取り込まれつ の機能や 用法を詳述したリファレンスマニュアルの つある．詳細な説明，最新の状況については当該ホー 作成を主目的とはしていないので，ソースコード内の ムページ 6をご覧いただきたい． コメント行を自動解析してこれを取り込み，その記述 をハイパーリンクや見出しや箇条書きなどの構造を ２．Fortran 90/95プログラムのドキュメント生成 持った HTM L 文書として生成する機能は有していな RDoc 以 外 に も，Fortran 90/95プ ロ グ ラ ム の ド い．また，PRIVATE 文によるモジュール中の言語 キュメント生成に関する試みはなされている．ここで 要素への参照不許可の指定や，構造データ型，多重定 は，f90doc と f90tohtml というソフトウェア お よ び 義などを用いたプログラムを正しく解析できないとい GFDL における取り組みについて紹介しておく． う問題もある． 7 f90doc は M IT の 計 算 科 学 グ ループ の Erik GFDL に お い て Isacc Held 氏 と Venkatramani Demaine 氏によって作成された Fortran 90/95用のド Balaji 氏が中心となって開発を行なっている気候モ キュメント自動生成 Perl スクリプトである．このソ デルの統合フレームワーク Flexible M odeling Sys- フ ト ウェア は Fortran 90/95ソース コード を 解 析 し tem（FMS)9では，ソースコード内のコメント行 に て，サブルーチンや関数の直前に記述されるコメント XM L 書式のドキュメントを埋め込むことで，ドキュ から HTM L 形式のドキュメントを生成す る．さ ら メントの作成と管理の手間を軽減している．HTML 6 「RDoc Fortran 90/95ソースコード解析機能強化版」 http://www.gfd-dennou.org/library/dcmodel/ rdoc-f95/＜参照2007/01/18＞ 7 「f90doc homepage」http://theory.lcs.mit.edu/ edemaine/f90doc/＜参照2007/01/18＞ 78 形式のドキュメントを生成する場合には，ソースコー 8 9 「f90tohtml Homepage」http://mensch.org/ f90tohtml/＜参照2007/01/18＞ 「FM S：the flexible modeling system」http:// www.gfdl.noaa.gov/ fms/＜参照2007/01/18＞ 〝天気" 54．2． RDoc を用いた数値モデルのドキュメント生成 187 ドから XM L 部 を抽出し，変換を行うようにしてい 簡単になる．２点目の特徴は，コメントとして記述す る．この手法 の 詳 細 は FMS プ ロ ジェク ト の ホーム る文書に簡素なタグを付加することで，箇条書きやハ 開されている 10．FM S で用いられてい イパーリンク等の文章構造を HTML ドキュメントに る手法では，ドキュメントを XM L で記述するため， 付与できることである．この機能により，ソースコー ドキュメントにハイパーリンクや箇条書きなどの構造 ドの可読性をさほど犠牲にすること無く， を持たせることが可能であるという利点がある．しか 良いドキュメントの作成が可能となる．３点目の特徴 し，コメント行に XM L タグを数多く記述する必要が はクロスリファレンスと呼ばれる機能を持つことであ あり，Fortran 90/95プログラムとしてのソースコー る．これは，複数のプログラムからドキュメントを生 ドが読みにくくなるという欠点がある．また現時点で 成する際に，コメント行に記述されたクラス名やメ は，ソース コード か ら XM L 部 ページ上に い勝手の を 抜 き 出 し， ソッド名を自動的にそのクラスやメソッドのドキュメ HTM L 形式のドキュメントを生成するソフトウェア ントへのハイパーリンクへと変換する機能である．本 は 開されておらず，この手法を誰でもがすぐに利用 来，ハイパーリンクを作成する際には，HTM L とし できるようにはなっていない． て表示する文字列およびリンク先の URL，そしてハ このように，気象学 野のモデルを含めた Fortran イパーリンクであることを示すタグを記述する必要が 90/95プログラムにおいても，他の言語と 同 様 に ド ある．クロスリファレンス機能により，これらの文字 キュメント作成と管理のための試みはなされつつあ 列とタグを記入すること無く，コメント行中にクラス る．しかし，Rubyや Java などの言語のように，プ 名やメソッド名を書いておくだけでハイパーリンクが ログラムとドキュメントを１つのファイルとして管理 自動作成される．これによって，コメントを記述する でき，かつプログラム中のコメント行に簡素なタグを 手間を減らすことができるだけでなく，ソースコード 付加することによってハイパーリンクや箇条書きなど の可読性の低下を防ぐこともできる． の構造を持つ HTML ドキュメントを自動生成できる RDoc は Rubyの み な ら ず，Fortran 90/95ソース ような手法は未だに確立されておらず，モデルのド コードの解析機能も有している．しかし，残念ながら キュメント整備のための手間の軽減は思うようには進 既存の RDoc ユーティリティーでは，Fortran 90/95 んでいない． プログラム中のファイルやモジュールやサブルーチン 以外のプログラム要素，すなわち関数や変数などを解 ３．RDoc の特徴 析することができなかった．また Fortran 90/95プロ RDoc はプログラムを解析し，ソースコードから得 グラムのドキュメントとしては必須である，サブルー ら れ る 情 報 と，コ メ ン ト 行 に 記 述 さ れ た 文 書 か ら チンの引数の情報，すなわちデータ型，INTENT 属 HTM L 形 式（正 確 に は XHTM L 1.0 Transitional 性（授 受 特 性)，引 数 キーワード な ど が 解 析 さ れ な 形式）のドキュメントを生成するライブラリである． かった．そしてコメントを解釈してドキュメントに取 RDoc が主に対象としているのはもちろん Rubyスク り込む機能も正しく働かないという問題があった． リプトであり，Rubyの標準ライブラリのドキュメン トの多くは RDoc によって作成されている． ４．RDoc Fortran 90/95解析機能の強化 RDoc の特徴として，以下の３点が挙げられる．１ 我々は，前節で述べた問題点を解決するとともに， 点目は，Rubyのソースコードを解析することによっ より充実した情報を持つ Fortran 90/95プログラムの て，クラス名やメソッド名，クラス間の継承の関係な リファレンスマニュアル自動生成が可能となるよう どを自動的にドキュメントに反映することである．こ に，RDoc の Fortran 90/95ソースコード解析機能の の機能により，ソースコードに記述する内容をドキュ 改良，強化を行った．我々が改良を施した RDoc は， メントに再度記述する必要が無くなり，ソースコード Fortran 90/95ソースコードのほとんどの言語要素， の内容に すなわち主プログラム，モジュール，サブルーチン， った最新のドキュメントを整備することが 10 「The FMS M anual A developers guide to the GFDL Flexible M odeling System」http://www. gfdl.noaa.gov/ vb/FM SM anual/＜参 照2007/01/ 18＞ 2007年 2月 関数，変数，定数，構造データ型，利用者定義演算 子，利用者定義代入，NAMELIST 文を解析するこ とができる．それらの言語要素の直後（行末もしくは 直後に続く行）に書かれたコメント行は，その言語要 79 188 RDoc を用いた数値モデルのドキュメント生成 素の解説文章として識別さ れる．この他にもモジュー ル間の依存関係， 称名を 用 い た 多 重 定 義， PRIVATE 文 に よ る モ ジュー ル中の言語要素の参照不許 可の指定なども解析可能で ある．サブルーチンや関数 に 関 し て は，そ の 引 数 の データ 型，INTENT 属 性 （授受特性)，引数キーワー 第１図 例として用いる Fortran 90/95プログラム．(a）は主プログラム，(b） は主プログラムから参照されるモジュールを記述したファイルである． ドをソースコードから自動 的に解析すると共に，引数 の宣言文の直後に書かれたコメントをその引数に関す グラムを るドキュメントとして識別する． れたファイル，(b）は主プログラムから参照される Fortran 90/95のソースコード解析機能以外にもい くつかの改良を行なっている．オリジナルの RDoc える．(a）は主プログラム calc が記述さ モジュール integral が記述されたファイルである． (2) ドキュメントの生成 では実現できていない，ファイル名のクロスリファレ ドキュメント生成はコマンドライン上から行う．プ ンス機能を追加した．また，北海道大学数学専攻の黒 ログラムの置いてあるディレクトリへ移動した後，以 田 拓氏による Ruby用 MathML ライブラリ 11を組 下のようにコマンド入力する． み込む機能を RDoc に付加することで，TeX 形式の 数式をコメントに埋め込んだ場合，その数式を Math- ％ rdoc --ignore-case --inline-source これにより doc/というディレクトリが作成される． ML 形式に変換してドキュメントに反映するようにし doc/index.html をブラウザで閲覧すると，第２図に た． 示されるようなドキュメントが表示される．上部のフ 以上の試みは現在 RDoc のオリジナルライブラリ 3 に順次組み込まれつつある．詳細は我々の レーム に は ファイ ル（ Files の 欄)，モ ジュール 開ホーム （Classes の欄)，サブルーチン，関数など（Methods ページ 6を参照していただくことにし，次節で具体例 の欄）のリストが表示される．下部のフレームにはサ を簡単に紹介することにする． ブルーチンや関数に関する情報が記載された，簡単な リファレンスマニュアルが表示される． ５．RDoc による数値モデルのドキュメント生成 (3) ドキュメント用文書の埋め込み ここでは RDoc 強化版を用いたドキュメントの生 上記のプログラムに実際にドキュメント用文書を埋 成方法を，実例を挙げて紹介する．RDoc 強化版は， め込んでみる．基本的にはサブルーチンや関数など， Rubyがインストールされている計算機環境なら容易 言語要素の宣言文の行末もしくは直後の行にコメント に導入することができる．具体的なインストール方法 を記載する．HTM L ドキュメントに箇条書きやハイ は RDoc 強化版ホームページ 6をご覧いただきたい． パーリンクなどの構造を持たせたい場合は，以下のタ (1) Fortran 90/95プログラムの作成 グを用いる． 例として，第１図に示す簡単な Fortran 90/95プロ 見 出 し：行 頭 に“＝”，“＝＝”，“＝＝＝”， “＝＝＝＝”を記述する．“＝”の数が見出しの 11 「ひらくの工房-MathM L ライブラリ」http://www. hinet.mydns.jp/ hiraku/. MathM L とは XM L ベー スの数学用マークアップ言語であり，数式などの数 学的情報も HTM L のように Web 上で 開，受信， レベルに対応する． 箇条書き：行頭に“＊” ，または“-”を記述する． 番号付き箇条書きは“１．” ，“２．” ，...，ア 処理することを目的としたものである．詳しくは ル ファベッ ト 付 き 箇 条 書 き は “ A． ”， 「W 3C Math Home」http://www.w3.org/M ath/を 参照されたい．＜参照2007/01/18＞ “B．” ，...，を記述する．入れ子にする場合， 80 半角２文字 字下げして再度行頭に上記の文字 〝天気" 54．2． RDoc を用いた数値モデルのドキュメント生成 189 イルやクラスやメ ソッドのドキュメン ト へ の リ ン ク は， ファイル名やクラス 名やメソッド名をそ のまま記述する． 数式の MathM L 表示： TeX 書 式 の 数 式 を ＄∼＄もしくは￥［ ∼￥］で括る． 文字の修飾：文字を斜体 で表示する場合は， “ word ”もしくは 第２図 RDoc を用いて作成した，第１図のプログラム群のドキュメント． “ ＜ em＞ word＜ / ，太字で表示 em＞” す る 場 合 は，“＊ word ＊”も し く は “ ＜ b ＞ wo r d ＜ / ，等 幅 で 表 示 b＞” す る 場 合 は“＋ word＋”も し く は “ ＜ t t ＞ wo r d ＜ / tt＞”と記述する． 第 １ 図（ b）の ソース コードにドキュメント用文 書を埋め込んだ具体例を第 ３図に示す． これらのプログラムか ら，再 度 RDoc に よって ドキュメントを生成する． 今回示す例のようにコメン 第３図 第１図 b のソースコードのコメント行にドキュメント用文書を埋め 込んだもの． トに日本語を埋め込む場合 には，ファイルの文字コー ドに応じた引数オプション を 指 定 す る．下 記 で は を記述する． ラ ベ ル 付 き 箇 条 書 き：ラ ベ ル を 角 括 弧 で 括 る （ “［label］contents” )，またはラベルと内容を “：：”で区切る（“label：：contents”)． “euc-jp”を指定している．また，TeX で記述した数 式を MathML で表示するために“--mathml”オプ ションも 用する． ％ rdoc --ignore-case --inline-source ￥ ハイパーリンク：表示する文字をリンク先の URL と同じにする場合は， “http://”などで始まる --charset euc-jp --mathml ここで“￥”は継続行を表す．doc/ディレクトリ URL をそのまま記述する．表示する文字とリ の内容が ン ク 先 の URL を 別 に す る 場 合 は，“｛dis- ラウザで閲覧する．今度は trapezoid 関数の部 ［URL］”と記述する．ファ played message｝ 第４図に示されるようなドキュメントが表示されるは 2007年 2月 新されるので，再度 doc/index.html をブ に， 81 19 0 RDoc を用いた数値モデルのドキュメント生成 ていただきたい． ６．おわりに この小論で紹介した RDoc 強化版はプログラム の規模によらず簡単に 用 することができる．また， プログラム中に全くコメン トが無くても第２図に示す 程度のドキュメントを生成 す る こ と は で き る．し た がって，ドキュメント整備 におけるプログラム開発者 の手間の軽減だけでなく， ドキュメントの用意されて いないプログラムの 用者 がプログラムを理解するた めの助けになることも期待 第４図 第３図に示した関数 trapezoid のドキュメント． できる．我々は，このライ ブラリの利 性と完成度を ずである．この図では，先ほどソースコードのコメン 高めるべく，今後も継続して改良を施していく予定で ト に 埋 め 込 ん だ 記 述（“＝＝＝”や“＊”，URL， ある．読者からのコメントや意見，情報などがあれ TeX の数式など）が HTM L における見出し，箇条 ば，筆者ら開発グループ宛（E-mail：dcmodel-rqst 書きなどへと変換されている．なお，M athM L を第 ＠gfd-dennou.org）にお寄せいただきたい． ４図のように表示するためには，ブラウザが MathML に対応している必要がある．対応ブラウザなどの このライブラリが，数値モデルに携わる方々の手助 けになれば幸いである． 情報に関しては RDoc 強化版ホームページ 6を参照し 82 〝天気" 54．2．