From: Takao Kouji <kouji@...7.net>
Date: 2008-07-20T15:57:30+09:00
Subject: [ruby-dev:35599] Readline::HISTORYの特異メソッドのrdocの書き方について

高尾宏治です。

Readline モジュールの rdoc を書いています。
rdoc の書き方について教えてほしいことがあります。

Readline モジュールには HISTORY という定数があります。
これは、入力履歴にアクセスするためのものです。
HISTORY[0] で入力履歴の最初のものにアクセスできます。

この HISTORY は、ext/readline/readline.c の
Init_readline 関数で次のようにして作成しています。
----- ここから -----
    history = rb_obj_alloc(rb_cObject);
    rb_extend_object(history, rb_mEnumerable);
    rb_define_singleton_method(history,"to_s", hist_to_s, 0);
    rb_define_singleton_method(history,"[]", hist_get, 1);
    rb_define_singleton_method(history,"[]=", hist_set, 2);
    rb_define_singleton_method(history,"<<", hist_push, 1);
    rb_define_singleton_method(history,"push", hist_push_method, -1);
    rb_define_singleton_method(history,"pop", hist_pop, 0);
    rb_define_singleton_method(history,"shift", hist_shift, 0);
    rb_define_singleton_method(history,"each", hist_each, 0);
    rb_define_singleton_method(history,"length", hist_length, 0);
    rb_define_singleton_method(history,"size", hist_length, 0);
    rb_define_singleton_method(history,"empty?", hist_empty_p, 0);
    rb_define_singleton_method(history,"delete_at", hist_delete_at, 1);
----- ここまで -----

Readline::HISTORY[-1] などは、例外 IndexError を発生します。
また、入力履歴を操作できない環境 (libedit の古い版) もあります。
これを Readline::HISTORY の特異メソッドの rdoc の中に書こうと考えていたのですが、
書き方が分かりませんでした。

次のようなものを想定していましたが、
rdoc 的に正しくないようです。
----- ここから -----
/*
 * call-seq:
 *   Readline::HISTORY.to_s -> "HISTORY"
 *
 * return "HISTORY".
 */
static VALUE
hist_to_s(VALUE self)
{
    return rb_str_new2("HISTORY");
}

----- ここまで -----

何か参考になる情報とかを教えていただけないでしょうか。
なお、 HISTORY の定数の説明に書くこともできるのでしょうが、
できるならば、特異メソッドの rdoc を書いた方が
メンテナンスも分かりやすさも上のように思っています。

以上、よろしくお願いします。