Rubyでドキュメントを作る方法

前回は関数を書いたので、今日は関数コメントについてつらつらと述べます。
関数コメントとは名前の通り、関数のコメントです。
書かなくてもいいものですが、説明があったほうが分かりやすいので書いたほうがいい。
ただし、privateなどを使う関数つまり、外側からは見れないバックで動く関数には関数コメントは書かない。
何故なら関数コメントは"rdoc"コマンドでhtml形式でドキュメントが生成されるからです。

↓はコメントのテンプレートになります。

#
#=== 概要
#
#(関数の概要を記述)
#
#=== 引き数
#
# +仮引数名+::
#(仮引数の説明を記述)
#
#=== 戻り値
#
#(戻り値の説明を記述)
#
#
#=== 詳細
# (詳細なセs詰め意を記述
#　箇条書きの場合、"*"と空白を書いてから内容を記述)
# 
# 
#
def func(...

前回書いたcalc_integer.rbに関数コメントを書いてみた

#整数型の演算を行う

#
#=== 概要
#
#コンソールから入力された整数値
#
#=== 詳細
#
# * プロンプト「Enter numeric value」を表示する
# コンソール入力を読み取る
# Integer関数を呼び出して整数値に変換する
#
def read_integer()
  puts("Enter numeric value")
  s = gets()
  i = Integer(s)
end

# === 概要
#
#2項演算の結果を表示する
#
# === 引数
#
# +operator+::
# 文字列で演算子を指定する
# +y+::
# 左項
# +x+::
# 右項
# +result+::
# 演算結果
#
#  === 戻り値
#
#  意味を持たない
#
#  === 詳細
#
#  * 引数で指定された情報をコンソールへ出力する
#
def show_result(operator, x, y, result)
  puts("#{x} #{operator} #{y} = #{result}")
end

ix = read_integer()
iy = read_integer()
show_result("+", ix, iy, ix + iy)
show_result("-", ix, iy, ix - iy)
show_result("*", ix, iy, ix * iy)
show_result("/", ix, iy, ix / iy)
show_result("**", ix, iy, ix ** iy)

これをコンソールでrdocコマンドで実行する

rdoc --charaset=shift_jis calc_integer.rb

すると、calc_intefer.rbがあるディレクトリ内にdocディレクトリができる。この中にある"indeex.html"をみると、関数コメントがhtml形式になったドキュメントが見れる。
この機能は本当面白い。今までこんなのがあるとは知らなかったので、今後これを何かの場面で使えたらいいと思う。ってか、このドキュメント生成ってどうなってんだろう。