moriqです。
バージョン依存コンパイルと文章表現について。
# これまた既出ならごめんなさい。
# ML検索ほしい！

  #@if (version >= "1.8.0")
  #@end
あるいは
  #@since 1.8.0
  #@end
を指定したときに
  ((<ruby 1.8 feature>)):
は削除しますよね。
このとき生じる表現上の問題について少し。


Rubyの仕様変更により、前のバージョンについて書かれた文を上書きする
必要があることがあります。

ここでは例としてArray#reverse, reverse!を挙げます。
次のような文章になっています。

  = class Array < Object
  --- reverse
  --- reverse!

  reverse は全ての要素を逆順に並べた新しい配列を返します。
  reverse! は配列の要素を逆順に(破壊的に)並べ替えます。

  reverse は、常に新しい配列を返しますが、reverse!  は、
  1 要素の配列に対して nil を返しそれ以外では self を返
  します
  #@if (version >= "1.8.0")
  ((<ruby 1.8 feature>)): 常に self を返します。
  #@end


この2段目以降を、バージョン1.8.0について簡潔に書くなら

  #@since 1.8.0
  reverse は新しい配列を返しますが、reverse! は self を返します。
  #@end

こうなると思います。


このように、v1.8.0以降の文が、その上にある文の単なる追加にならないことは
よくあると思います。

このような場合、ひとつの案としては、
1.8.0より前のバージョンを表すプリプロセッサを用意することが考えられます。

  #@if (version < "1.8.0")
  reverse は、常に新しい配列を返しますが、reverse!  は、
  1 要素の配列に対して nil を返しそれ以外では self を返
  します。
  #@end
  #@if (version >= "1.8.0")
  reverse は新しい配列を返しますが、reverse! は self を返します。
  #@end


しかし、
バージョン依存コンパイルは文の追加だけに対応するという方針もありでしょう。
この方針なら、表現を工夫する必要があります。

  reverse は、常に新しい配列を返しますが、reverse!  は、
  1 要素の配列に対して nil を返しそれ以外では self を返
  します。
  #@since 1.8.0
  1.8.0以降では常に self を返します。
  #@end

ここで、プリプロセッサを使っていても、文中にバージョンが現れています。
これは許されますか。


あるいは、レンダリングするときに#@since 1.8.0をそれらしく変換するなら、
文中にバージョン表記は必要ないでしょう。

  レンダリング結果:
  reverse は、常に新しい配列を返しますが、reverse!  は、
  1 要素の配列に対して nil を返しそれ以外では self を返
  します。
  --[1.8.0以降]---------
  常に self を返します。
  ----------------------

# でもどちらにしろこの文じゃ「常に self を返します。」がどこに掛かって
# いるのか分かりにくいな。


まとめると、
  * 前のバージョンを表すプリプロセッサを用意する。
or
  * バージョン依存コンパイルは文の追加だけに対応。
    説明を上書きする必要がある場合は、表現を工夫する。
or
  * バージョン依存コンパイルは文の追加だけに対応。
    レンダリング時に#@sinceで指定したバージョンを出力する。
    適用される範囲が囲みになるとなおよい。

のいずれかになるかなと思います。
いかがでしょう。

--
ML: ruby-reference-manual@m...
使い方: http://QuickML.com/