[dennou-ruby:002223] parse_f95.rb in rdoc

[Morikawa Yasuhiro <morikawa@xxxxxxxxxxxxxxxxxxxx>]

dcmodel のみなさま
dennou-ruby のみなさま

森川＠北大  です

先日の dennou-ruby workshop にて RD と rdoc の f90 ソースコード
への応用ということで発表させていただきました。

  http://ruby.gfd-dennou.org/workshop200503/shiryou/index.htm
  http://www.gfd-dennou.org/arch/prepri/2005/ruby/RDinF90/RDinF90.htm

この中で、f90 ソースコードを解釈してドキュメントを生成してくれる、
rdoc の parse_f95.rb というものを紹介しました。

  http://www.gfd-dennou.org/arch/prepri/2005/ruby/RDinF90/dcpam2_rdoc_sample/src/shared/rdoc/

使ってみた感じは、相互リンクや、ソース内のコメントを HTML として吐き出
してくれるなど、かなり有用そうである一方、f95 ソースのリファレンスマニュ
アルとしては (個人的には) 不足と思われる部分も多く、可能であれば 
parse_f95.rb を改良して利用したいと思いました。その際、堀之内さんから、
「とりあえずまずは rdoc の作者の Dave Thomas に連絡して要望を伝えたら？」
というアドバイスを戴きました。

既に個人的にいくつかの要望はあったのですが、直接作者御本人に伝える前に、
他にも「このようになってると便利だよなぁ」というアドバイスがあればそれ
も合わせて伝えられれば、と思い、ご意見を募る次第です。もちろん要望が全
てすぐに実装されるということはないのでしょうが、「Fortran90 のドキュメ
ントはどうあると嬉しいか (自動生成でどこまで可能か)」という議論にもな
れば、個人的には勉強になって嬉しいです。

# 個人的には、上記の発表資料の RD の f90 への応用の際に「ドキュメントに
# 書き出す部分」として考えた部分が、rdoc でもドキュメント化できると満足
# です。


= parse_f95.rb への要望 (欲張りすぎ…？  ^^;)

なお、今の僕が使っている環境は ruby 1.8.2 (2005-01-10) で、
RDoc V1.0.1 - (20041108) です。

  * parse_rb.rb には実装されていて、parse_f95.rb には実装されていない部分。

    * 現在の parse_f95.rb は、一つの f95 ファイルに複数の module がある
      場合、ruby ソース用の parse_rb.rb と異なり、始めの module しか識別
      しないようになっているので、複数の module であっても識別してドキュ
      メントに反映するようにしたい。

    * module の部分よりも前に書いてある記述は class **** のドキュメントの
      ページではなく、*****.f95 のドキュメントのページに書き出したい。
      (つまり、parse_rb.rb のようにしたい)。

    * ruby ソース用の parse_rb.rb のように、サブルーチンや関数、構造体の
      public や private を判定したい。

    * [Source] で表示されるソースの色分けをしたい。
      * おそらく、parse_rb.rb での色分けロジックを応用すれば
	難しくないのでは…。


  * f95 ドキュメント特有のもの

    * 各メソッドにて [Source] でメソッド内のソースが見えるように、
      ファイル自体のドキュメントのページでファイル内のソース全体
      が見えるリンクを作りたい。

    * 構造体の定義の部分をドキュメントに出力したい。

    * 総称名称 (module procedure の部分) を出力したい。

    * NAMELIST 変数に関しても出力したい。
      * NAMELIST 変数に属する変数の初期値も出力したい。
        (同じスコープ内の同名の変数を探すことで探査可能ではないか？)

    * 公開要素 (public 属性) の変数も出力したい。
      * 例えば、http://www.gfd-dennou.org/arch/prepri/2005/ruby/RDinF90/dcpam2_rd_sample/src/shared/constants/constants.htm
        の「Public Data」のようなものを出力したい。
      * 実際には、public 行のサブルーチン、関数、変数のうちの変数の
        宣言文の部分 (型と初期値) を出力してくれると嬉しい。

    * モジュール全体だけでなく、各サブルーチンでも同じモジュールを use
      する可能性があるので、重複するものに関しては Included Modules から
      省いて欲しい。(各サブルーチンや関数を見る場合に、モジュールの
      頭に use が固まってるのは結構読みづらいので…)。

┌□─────────────────────────
■    森川 靖大 (Morikawa Yasuhiro)
｜□  北海道大学大学院 理学研究科 地球惑星科学専攻
■    地球流体力学研究室 修士課程 2 年
｜□  e-mail : morikawa@xxxxxxxxxxxxxxxxxxxx
■──────────────────────