rubyベストプラクティスchapter8.3

rdocの便利機能の紹介

簡単な例も書かれているのですが、とりあえず飛ばして便利機能を

nodoc

rdocに含めたくないものに指定する。
メソッドレベル

def hoge # :nodoc:
end

クラスレベル

class Hoge # :nodoc:
end

ってやるとrdocには出力されない。
ただし、上記のHogeクラスをnodocにしてもHoge::Fooはnodocにならない。個別に指定しましょう。

class Hoge # :nodoc:
  class Foo   # ここはnodocにならない
  end
end

「:nodoc: all」にすると継承先もnodocになる。

class Hoge # :nodoc: all
  class Foo   # ここもnodocになる
  end
end

このnodocにはライブラリの作者が「このクラス(メソッド)はユーザにはあまり使って欲しくないですー」ってメッセージも込められているらしい。

call-seq

よくわからん。。。
ということで写経とrdocコマンドで確認
まずはサンプル。:call-seq:ありバージョン

# :call-seq:
#   bounding_box(point, options={}, &block)
#
# A bounding box serves two important purposes:
# * Provide bounds for flowing text, starting at a given point
# * Translate the origin (0,0) for graphics primitives, for the purposes
# of simplifying coordinate math.
# (rest omitted, as this documentation is pretty lengthy)
#
def bounding_box(*args, &block)
  init_bounding_box(block) do
    translate!(args[0])
    @bounding_box = BoundingBox.new(self, *args)
  end
end

これをrdocするとメソッドの引数の説明がcall-seqで指定したものになる。
こんな感じ。

Public Instance Methods
bounding_box(point, options={}, &block)

でcall-seq無しの場合は

Public Instance Methods
bounding_box(*args, &block)

こうなる。実際の引数をそのまま使う。
もっと極端にcall-seqをものすごく意味の無いものにする。

# :call-seq:
#   hogehoge(foo, bar, yhaaa)
#
# A bounding box serves two important purposes:
# * Provide bounds for flowing text, starting at a given point
# * Translate the origin (0,0) for graphics primitives, for the purposes
# of simplifying coordinate math.
# (rest omitted, as this documentation is pretty lengthy)
#
def bounding_box(*args, &block)
  init_bounding_box(block) do
    translate!(args[0])
    @bounding_box = BoundingBox.new(self, *args)
  end
end

Public Instance Methods
hogehoge(foo, bar, yhaaa)

こうなる。

section

このタグを使うとrdocの作成時に一つにまとめて1ページつくってくれる。
通常はクラス毎、ファイル毎にページを作成するところを、機能単位にページを作れたりして便利。

字面はわかるんだけど。。。と思ったのでやっぱり写経。

module Prawn
  module Measurements

    # ------------------------------------------------------------
    # :section: Imperial Conversions
    # Convert several metric units to one another and to PDF points
    # ------------------------------------------------------------

    def ft2in(ft)
      return ft * 12
    end

    def in2pt(inch)
      return inch * 72
    end

    # ----------------------------------------------------------
    # :section: Metric Conversions
    # Convert sevral metric units to one anohter and PDF points
    # ----------------------------------------------------------

    def cm2mm(cm)
      return cm * 10
    end

    def mm2pt(mm)
      return mm*(72 / 25.4)
    end
  end
end

ってすると
こう出る。

サイドバーにsectionってリンクが出来ていてそこから追えるらしい。

では、別のファイルで同じsectionを入れるとどうなるか実験。

module Prawn
  module AnotherMeasurements

    # ------------------------------------------------------------
    # :section: Imperial Conversions
    # ------------------------------------------------------------

    def another_ft2in(ft)
      return "hoge"
    end

    def anohter_in2pt(inch)
      return "foo"
    end
  end
end

module Prawn
  module Measurements
    # ------------------------------------------------------------
    # :section: Imperial Conversions
    # ------------------------------------------------------------

    def foo
    end

    def bar
    end
  end
end

とすると同一のModuleであれば(ここではfooとbarメソッド)は先程のsectionに
まとめられて、別のModuleであれば(ここではanother_ft2inとanother_in2ptメソッド)
は別のsectionにまとめられる。

sectionの機能は同一moduleもしくはclassでの機能をまとめたページを作成する
機能なんですな。納得。

Rubyベストプラクティス -プロフェッショナルによるコードとテクニック