http://www.gfd-dennou.org

RDoc による数値モデルドキュメント作成（解説編）
北海道大学/神戸大学
森川 靖大
/161

第7回 地球流体電脳 davis/rubyワークショップ 2008 年 3 月 10 日 京大生存研遠隔講義室 HS109

はじめにドキュメントの重要性
第三者への提供 (プログラムの利用)
開発や保守の効率化 (プログラムの改変)

Fortran による数値モデルのドキュメント
数理、離散化ドキュメント :: TeX
数式の記述に最適

リファレンスマニュアル :: HTMLWeb からの参照に最適、ハイパーリンクが便利
http://www.gfd-dennou.org

2 /16

リファレンスマニュアルの作成

3 /16

何が厄介かというと...
プログラムとマニュアルを別々に用意するのは面倒プログラムで書いたものをもう一度書くのは面倒

Ruby でのマニュアル生成
RDoc によるマニュアルの自動生成

RDoc による数値モデルのマニュアル自動生成
RDoc の Fortran 90/95 の解析機能の強化

http://www.gfd-dennou.org

Ruby でのドキュメント生成

4 /16

リファレンスマニュアル作成には RDoc (Ruby
Document System) を使用
RDoc とは?
Ruby で書かれたソースコードから HTML、XML形式のマニュアルを自動生成する Ruby の標準ライブラリ (DaveThomas 氏作成)
ソースコードを自動解析
ソースコードに記述されるコメントもマニュアルに反映
自動生成される HTML 形式のマニュアルにハイパーリンクや見出し、箇条書きといった構造を付与することが可能 (そのために必要なタグも簡潔でソースコードを読む妨げにならない)

RDoc により、リファレンスマニュアルの作成と維持管理が容易となる
http://www.gfd-dennou.org

RDoc の Fortran 90/95 への適用

5 /16

RDoc の作者の Dave Thomas 氏が Parser の一つとして Fortran 90/95 用のものを作成

RDocGenerators

CodeObject
CodeObject

HTML
HTMLGenerator
Generator
XML
XMLGenerator
Generator

XMLXML

Reference manualHTMLHTML

http://www.gfd-dennou.org

Parsers
RubyRubyParser
Parser

ソースコード、マソースコード、マニュアルの形式
ニュアルの形式に拠らないオブに拠らないオブ
ジェクト
ジェクト

Fortran95
Fortran95Parser
Parser
CCParser
Parser

Source code
F95
F95

Ruby
RubyCCFortran95 Parser

6 /16

Fortran90/95 の文法を解釈
別ファイル内のモジュール等へ自動的にリンク作成
タグを埋め込めば、目次、リスト、テーブルも表現可能
Fortran95 ソースコード!= Module module̲name̲mod : Sample module! Authors:: Yasuhiro MORIKAWA!
! This module depends base̲mod module!
module sample̲moduse base̲modimplicit none
privatepublic :: sample̲init, sample̲end, Constreal(8) :: Const = 3.14
subroutine sample̲init(inchar, outint)character(*), intent(in) :: inchar
integer(INTKIND), intent(out):: outint
end subroutine sample̲init
subroutine sample̲end(err)logical, intent(inout) :: err
end subroutine sample̲end
end module sample̲mod

http://www.gfd-dennou.org!=!= Module
Module ..
.. ①!! Authors::
Authors:: ..
..

① RDoc のタグは “=“ や“::” で表記use
use base̲modbase̲mod ②::
modulemodule module̲..
module̲..
::subroutine
subroutine mo..
mo..
::
end
end subrou..
subrou..
end
moduleend module modu..
modu..

② module 文, use 文,
subroutine 文を解釈。
別ファイルのモジュー
ルへのリンクを自動で作成

Fortran95 Parser

7 /16

Fortran90/95 の文法を解釈
別ファイル内のモジュール等へ自動的にリンク作成
タグを埋め込めば、目次、リスト、テーブルも表現可能
Fortran95 ソースコード!= Module module̲name̲mod : Sample module! Authors:: Yasuhiro MORIKAWA!
! This module depends base̲mod module!
module sample̲moduse base̲modimplicit none
privatepublic :: sample̲init, sample̲end, Const

RDoc
RDocreal(8) :: Const = 3.14
subroutine sample̲init(inchar, outint)
character(*), intent(in) :: inchar
integer(INTKIND), intent(out):: outint
end subroutine sample̲initsubroutine sample̲end(err)logical, intent(inout) :: err
end subroutine sample̲end
end module sample̲mod

http://www.gfd-dennou.org

HTML のリファレンスマニュアル
Files

ClassesMethods

sample.f90
base.f90

sample_mod
base_modsample_init
sample_end

Class sample_mod
In: sample.f90

Module sample_mod : Sample module
Authors: Yasuhiro MORIKAWA
This module depends base_mod module

Methods
sample_init sample_end
Included Modules
base_modPublic instance methods
sample_init (inchar, outint)[source]sample_end (err)[source]aaa
ハイパーリンク
ハイパーリンクFortran 90/95 解析機能の強化8 /16

Fortran 90/95 のリファレンスマニュアル自動生成ツールとして実用化一通りの言語要素を解析
Fortran なので引数の型の情報もマニュアルに反映
TeX 形式で記述したコメントを、コンパイルされた形式で表示可能とする (黒田拓氏の Ruby 用
MathML ライブラリを使用)

http://www.gfd-dennou.org

一通りの言語要素と引数の解析

構造体の解析
構造体の解析

要素、要素の型、解説の表示
要素、要素の型、解説の表示

http://www.gfd-dennou.org

9 /16

一通りの言語要素と引数の解析

定数の解析
定数の解析

型、初期値、解説の表示
型、初期値、解説の表示

http://www.gfd-dennou.org

10 /16

一通りの言語要素と引数の解析関数の解析
関数の解析解説の表示
解説の表示

http://www.gfd-dennou.org

11 /16

一通りの言語要素と引数の解析

引数の解析
引数の解析型、解説の表示
型、解説の表示

http://www.gfd-dennou.org

12 /16

一通りの言語要素と引数の解析

public,public, private
privateを区別
を区別

http://www.gfd-dennou.org

13 /16

一通りの言語要素と引数の解析

変数の解析
変数の解析

型、初期値、解説の表示
型、初期値、解説の表示

http://www.gfd-dennou.org

14 /16TeX を数式として表示

15 /16

コメントに TeX 形式で記述した数式をMathML に変換! ¥[! ¥int̲{a}^{b} f(x) dx =!
¥frac{h}{2} ¥left¥{ f(a) + f(b) ¥right¥} + h¥sum̲{i=1}^{n‑1} f(a+ih)! ¥]Ruby 用 MathML ライブラリを使用
http://www.hinet.mydns.jp/?mathml.rb

MathML 対応ブラウザが少なめなのが問題
Firefox、Internet explorer ぐらい…?
http://www.gfd-dennou.org

まとめ

16 /16

RDoc Fortran 90/95 解析機能強化版により、数値モデルのリファレンスマニュアル生成が簡
単に公開URL
http://www.gfd-dennou.org/library/dcmodel
パッチを当てたパッケージも配布してます
コメントの書法等の解説あります

使用例
http://www.gfd-dennou.org/library/gtool4
http://www.gfd-dennou.org/library/dcpam
http://www.gfd-dennou.org/library/deepconv
http://www.gfd-dennou.org

参考資料

17 /16

数値モデリングプロジェクト dcmodel
http://www.gfd-dennou.org/library/dcmodel/

森川靖大, 石渡正樹, 堀之内武, 小高正嗣, 林祥介, 2007: RDoc を用いた数値モデルのドキュメント生成. 天気, 54, 185--190.
http://s-ws.net/tenki/cont/54_02/co.htmlオブジェクト指向スクリプト言語 Ruby
http://www.ruby-lang.org

Ruby 用 MathML ライブラリ
http://www.hinet.mydns.jp/?mathml.rb

MathMLによる数学的文書の作成と公開のシステム （講演者: 黒田 拓氏）
http://www.hinet.mydns.jp/presentation/hiki.cgi?MathML2006.03

Fortran からドキュメントを自動生成するツール
f90tohtml
http://mensch.org/f90tohtml/

f90dochttp://theory.lcs.mit.edu/~edemaine/f90doc/

http://www.gfd-dennou.org

http://www.gfd-dennou.org

付録/1618

CodeObject

19 /16

ソースコード内の情報を階層的に保持するためのオブジェクト
CodeObject ： 共通する情報
TopLevel ： ファイルの情報
ClassModule ： クラス、モジュールの情報
AnyMethod： メソッドの情報

継承の関係
CodeObject

TopLevel
http://www.gfd-dennou.org

ClassModule

AnyMethodソースコード ⇒ CodeObject

20 /16

ソースコード内の情報を TopLevel,
ClassModule, AnyMethod へ
Source code

個々のファイル毎に、クラス・モ個々のファイル毎に、クラス・モ
ジュール・メソッドの定義、クラスのジュール・メソッドの定義、クラスの継承関係、クラス・モジュールの依継承関係、クラス・モジュールの依存関係を抽出
存関係を抽出Parsers

TopLevel
ClassModule

ClassModule

AnyMethod
AnyMethod

AnyMethod

AnyMethod

http://www.gfd-dennou.org

TopLevel
ClassModule

AnyMethod

AnyMethod
AnyMethod

TopLevelCodeObject ⇒ マニュアル

21 /16HTML 等のドキュメントを生成
TopLevel
ClassModule

ClassModule

AnyMethod
AnyMethod

AnyMethod

TopLevel
ClassModule

AnyMethod

http://www.gfd-dennou.org

TopLevelAnyMethod
AnyMethod

Generators

XMLXML

AnyMethod

HTMLHTML

Reference manual

全てのオブジェクトを集約
全てのオブジェクトを集約した後、リファレンスマニュした後、リファレンスマニュ
アルを生成
アルを生成

Fortran95 Parser (強化版)

22 /16

解析機能の強化の具体例
Fortran95 ソースコード!= Module sample̲mod : Sample module! Authors:: Yasuhiro MORIKAWA!
module sample̲moduse base̲mod!
! sample̲mod の概要
implicit none
privatepublic :: sample̲init, sample̲func, const, TYPE̲A
private:: internal
type TYPE̲A! 構造体の解説
integer :: counterend type TYPE̲A! 構造体内部の変数の解説

real(8), parameter :: const = 3.14
integer, save:: internal! 公開定数! 非公開変数

subroutine sample̲init(inchar, outint)! 初期化サブルーチン
character(*), intent(in) :: inchar
integer(INTKIND), intent(out):: outint
end subroutine sample̲init! 入力変数! 出力変数function sample̲func(log) result(res)! 関数
logical, intent(in) :: log ! 論理型入力変数
logical:: res ! 論理型の返り値
end function sample̲func
end module sample̲mod

http://www.gfd-dennou.org

public::public:: samp...
samp...①
private::private:: inte...
inte...

① 公開要素と非公開要素の区別

type
type TYPE̲ATYPE̲A ...
... ②② 構造体③
real(8),real(8), parame..
parame..
Integer,Integer, save..
save..

③ 公開定数、公開変数!! 初期化...
初期化...

④⑤char..
!! 入力..
char..
入力..
integer..
integer.. !! 出力..
出力..
functionfunction samp...
samp...⑥::
end
end function
function ..
..

④ サブルーチン、関数のコメント⑤ 引数の型、
コメント⑥ 関数

Fortran95 Parser (強化版)
解析機能の強化
解析可能になった要素のリスト
関数 (function 文)
サブルーチンや関数の引数の型
モジュールが公開する変数, 定数
構造体 (type 文)
NAMELIST 文
利用者定義演算子 (operator), 利用者定義代入 (assignment)
上記要素のコメント文
総称手続き (interface 文)
公開要素と非公開要素との区別
孫引きされている公開要素

大文字小文字の違いを無視
http://www.gfd-dennou.org

23 /16