Title: 自動ドキュメント生成システム rdoc と Fotran90 プログラムへの適用例

目次
• RD と rdoc
  • RD
  • rdoc
  • 両者の比較
• RD を応用しての、Fortran90 ソースからのドキュメント自動生成
  • 事の起こり (去年の末ぐらい…？)
  • 主な狙いは？
  • 実際のソースとその結果
  • 課題
  • これから
• rdoc を応用しての、Fortran90 ソースからのドキュメント自動生成
  • 事の起こり (今月の頭ぐらい…？)
  • rdoc を DCPAM のソースコードに用いてみる。
  • rdoc は使えるか？
  • これからどうする？

1 RD と rdoc

1.1 RD

RD (Ruby Document) とは Ruby 関係のドキュメントを書くために考え出された 汎用のドキュメントフォーマット。

主に (私の偏見では) 以下の特徴を持つ。

• plain text に「比較的」近く、書きやすく読みやすい。
  • よって「比較的」、ソースコードを「汚さず」に済む。
    • 少なくとも HTML や TeX よりははるかに plain text に近い。 (例えば、この資料も書きやすいので RD で書いてます。^^; )
• rdtool によって HTML や TeX に変換できる。

詳しくは以下の URL を参照のこと。

• Just Another RD Site
• RD事始め

ただし、Ruby 本体のドキュメントは rdoc に移行したので、現在の Ruby のツールは RD ではなく、rdoc で記述されている。

1.2 rdoc

rdoc は Rubyのソースファイルに対するドキュメントを生成する アプリケーションである。 ソースを解析し、クラス、モジュール、メソッド の定義を抜き出してくれる (include,require も) ^*1。 そしてこれらの内容とその直前に書かれたコメントを併合し、 ドキュメントを出力する。(現在は HTML を出力できる)。

• 例
  • Ruby ソースと出力結果

詳しくは以下の URL を参照のこと。

• rdoc: Ruby Standard Library Documentation
• The RWiki - RDoc覚え書き
• RDOC - Ruby Documentation System

1.3 両者の比較

• RD の特徴
  • 汎用性が高いので、Ruby ドキュメントに限らず、メモ書きなどにも 利用できる。(少なくとも、最近私はメモ書きを RD で書いてます)
  • HTML や TeX, (出来栄えはさておき) roff 形式に出力可能である。
  • (rdoc に比べれば) 細かな修飾が可能である。
  • 汎用的で読みやすく書き換えやすいフォーマット
• rdoc の特徴
  • ソースを解析し、メソッドやクラスのリンクも自動で張ってくれるため、 非常にお手軽に、しかも完成度の高いドキュメントを作成可能。
  • (個人的な感想として) プログラムソースを書く際に「こう書いておくのが 自然だろうな」という書き方で書くとちゃんと rdoc でドキュメントを 生成するようになっている。
  • 「ソースコードをドキュメントに」ということに特化した アプリケーション

2 RD を応用しての、Fortran90 ソースからのドキュメント自動生成

RD 自体では、「ドキュメントを自動生成するソースの書き方」を規定 していないため、書法を定め、その parser をつくり、ドキュメントを 自動生成する必要がある。

DCPAM では、RD を 用いて実際に書法を定め、Fortran90 からのドキュメント自動生成を試みた。

2.1 事の起こり (去年の末ぐらい…？)

Fortran90 プログラムに対するドキュメントを作るのが面倒くさい。 特に、「既にソースコードに一度書いた部分」(例えば、サブルーチンの 引用仕様とか、公開要素とかとか) を再度書くのが鬱陶しい。

ただ、従来の HTML や TeX を埋め込むと逆に Fortran90 ソースのコードが 「穢れる」。

あ、RD だとうまくできるかも？

2.2 主な狙いは？

• プログラム内部に書くコメントなど、そのままマニュアルにできるように。
• サブルーチンの引用仕様など、ソースの変更をそのまま反映させたい。

2.3 実際のソースとその結果

• 書法
• 実際のソースと マニュアル の例

2.4 課題

• モジュール間、サブルーチン同士のリンクの体系が未整備
  • 何らかの parser が必要になるだろう
• (上記と関係があるが)、インデックスの体系も未整備
  • やっぱりなんらかの parser が必要

2.5 これから

• 案１ ： リンクやインデックスを整えるべく、parser を作成
• 案２ ： rdoc に移る？？？

3 rdoc を応用しての、Fortran90 ソースからのドキュメント自動生成

3.1 事の起こり (今月の頭ぐらい…？)

rdoc は Ruby ソースコードを HTML ドキュメントにする ものだと 思い込んで居て、Fortran90/95 のドキュメント化に関してはすっかり 蚊帳の外であったのだが、ruby に関して私の大先輩の daktu32 氏が Fortran90 用の parser である parse_f95.rb を見つけて来た ^*2 ことにより事態が急転。 ^*3

3.2 rdoc を DCPAM のソースコードに用いてみる。

The RWiki - RDoc覚え書き を参照して少々、先の実際のソースとその結果で見せたソースを rdoc 用に書き換えて rdoc をかけてみる。 ^*4

• rdoc 用に書き換えてみた ソースと マニュアル (群)、 (後日追加した、 --diagram オプション付きバージョン )

3.3 rdoc は使えるか？

• 課題 におけるリンクやインデックスの問題は素晴らしく解決している
• ただ、いくつか Fortran90 的には (個人的要望としては) もう一歩という ところも多い。(多分 parse_f95.rb 自体は parse_rb.rb と異なり 開発途上なのでしょうがないのだろうけど)
  • 例
    • 公開要素 (public 属性) の変数も出力できないか？
      • どうやら、まっとうに public か private は判定できてない。
    • NAMELIST も自動判別して出力できないか？
    • use の際の only も出力したい。
    • (Fortran90 は引数の方が決まっているので) intent 属性を判定 して欲しい。
    • 総称名称 (generic procedure) は出力したい。
    • などなど…

3.4 これからどうする？

個人的には、rdoc の parse_f95.rb を改良する方針が望ましいと 考えている。(まだ何もやってないけど)。 ^*5

それなりに大変かとは思うが、 RD を応用しての、Fortran90 ソースからのドキュメント自動生成 でリンクやインデックス作成用の parser を作る手間を考えれば 決して大変ではなさそう … か？？

^*1例えば似たようなものでは、Java における JavaDoc のようなものがある
^*2 普通に rdoc にパッケージングされていたものだが、それまで誰も 気づいていなかった…。
^*3その余波を受け、このような発表をする 羽目に合う機会を得たりもする。
^*4実際に自分で直接試したのは昨日 (2005/03/21) が初めて (-_-;)
^*5「何かする前に、作者の方にとりあえずお願いしましょう。 たぶんやってくれるよ？」 by 堀之内氏