rroonga 2.0.4-x86-mingw32 → 2.0.7-x86-mingw32

data/ext/groonga/rb-grn-table.c

@@ -35,7 +35,7 @@ static ID id_array_set;
  * Document-class: Groonga::Table < Groonga::Object
  *
  * rroongaが提供するテーブルのベースとなるクラス。このクラス
- * からGroonga::Array, Groonga::Hash, Groonga::PatriciaTrie
+ * から {Groonga::Array} , {Groonga::Hash} , {Groonga::PatriciaTrie}
  * が継承されている。
  */
 
@@ -204,10 +204,10 @@ rb_grn_table_inspect_content (VALUE self, VALUE inspected)
 }
 
 /*
- * call-seq:
- *   table.inspect -> String
- *
  * テーブルの中身を人に見やすい文字列で返す。
+ *
+ * @overload inspect
+ *   @return [String]
  */
 static VALUE
 rb_grn_table_inspect (VALUE self)
@@ -224,36 +224,31 @@ rb_grn_table_inspect (VALUE self)
 }
 
 /*
- * call-seq:
- *   table.define_column(name, value_type, options={}) ->
- *     Groonga::FixSizeColumnかGroonga::VariableSizeColumn
- *
  * テーブルに名前が _name_ で型が _value_type_ のカラムを定義
  * し、新しく定義されたカラムを返す。
  *
- * _options_ に指定可能な値は以下の通り。
- * @param options [::Hash] The name and value
- *   pairs. Omitted names are initialized as the default value.
- * @option options :path The path
- *   カラムを保存するパス。
- *
- * @option options :persistent (永続カラム) The persistent
- *   +true+ を指定すると永続カラムとなる。省略した場合は永
- *   続カラムとなる。 +:path+ を省略した場合は自動的にパスが
- *   付加される。
- *
- * @option options :type (:scalar) The type
- *   カラムの値の格納方法について指定する。省略した場合は、
- *   +:scalar+ になる。
- *
- *   [+:scalar+] スカラ値(単独の値)を格納する。
- *   [+:vector+] 値の配列を格納する。
- *
- * @param options :compress The compress
- *   値の圧縮方法を指定する。省略した場合は、圧縮しない。
- *
- *   [+:zlib+] 値をzlib圧縮して格納する。
- *   [+:lzo+] 値をlzo圧縮して格納する。
+ * @overload define_column(name, value_type, options={})
+ *   @param options [::Hash] The name and value
+ *     pairs. Omitted names are initialized as the default value.
+ *   @option options :path
+ *     カラムを保存するパス。
+ *   @option options :persistent (永続カラム)
+ *     +true+ を指定すると永続カラムとなる。省略した場合は永
+ *     続カラムとなる。 +:path+ を省略した場合は自動的にパスが
+ *     付加される。
+ *   @option options :type (:scalar)
+ *     カラムの値の格納方法について指定する。省略した場合は、
+ *     +:scalar+ になる。
+ *
+ *     - +:scalar+ := スカラ値(単独の値)を格納する。
+ *     - +:vector+ := 値の配列を格納する。
+ *   @option options :compress
+ *     値の圧縮方法を指定する。省略した場合は、圧縮しない。
+ *
+ *     - +:zlib+ := 値をzlib圧縮して格納する。
+ *     - +:lzo+ := 値をlzo圧縮して格納する。
+ *
+ * @return [Groonga::FixSizeColumn or Groonga::VariableSizeColumn]
  */
 static VALUE
 rb_grn_table_define_column (int argc, VALUE *argv, VALUE self)
@@ -364,37 +359,30 @@ n_gram_tokenizer_p(grn_ctx *context, grn_obj *tokenizer)
 }
 
 /*
- * call-seq:
- *   table.define_index_column(name, value_type, options={}) -> Groonga::IndexColumn
- *
  * テーブルに名前が _name_ で型が _value_type_ のインデックスカ
  * ラムを定義し、新しく定義されたカラムを返す。
  *
- * _options_ に指定可能な値は以下の通り。
- * @param options [::Hash] The name and value
- *   pairs. Omitted names are initialized as the default value.
- * @option options :path The path
- *   カラムを保存するパス。
- *
- * @option options :persistent (永続カラム) The persistent
- *   +true+ を指定すると永続カラムとなる。省略した場合は永
- *   続カラムとなる。 +:path+ を省略した場合は自動的にパスが
- *   付加される。
- *
- * @option options :with_section The with_section
- *   転置索引にsection(段落情報)を合わせて格納する。
- *
- * @option options :with_weight  The with_weight
- *   転置索引にweight情報を合わせて格納する。
- *
- * @option options :with_position The with_position
- *   転置索引に出現位置情報を合わせて格納する。
- *
- * @option options :source The source
- *  インデックス対象となるカラムを指定する。 +:sources+ との併用はできない。
- *
- * @option options :sources The sources
- *  インデックス対象となる複数のカラムを指定する。 +:source+ との併用はできない。
+ * @overload define_index_column(name, value_type, options={})
+ *   @param options [::Hash] The name and value
+ *     pairs. Omitted names are initialized as the default value.
+ *   @option options :path
+ *     カラムを保存するパス。
+ *   @option options :persistent (永続カラム)
+ *     +true+ を指定すると永続カラムとなる。省略した場合は永
+ *     続カラムとなる。 +:path+ を省略した場合は自動的にパスが
+ *     付加される。
+ *   @option options :with_section
+ *     転置索引にsection(段落情報)を合わせて格納する。
+ *   @option options :with_weight
+ *     転置索引にweight情報を合わせて格納する。
+ *   @option options :with_position
+ *     転置索引に出現位置情報を合わせて格納する。
+ *   @option options :source
+ *    インデックス対象となるカラムを指定する。 +:sources+ との併用はできない。
+ *   @option options :sources
+ *    インデックス対象となる複数のカラムを指定する。 +:source+ との併用はできない。
+ *
+ * @return [Groonga::IndexColumn]
  */
 static VALUE
 rb_grn_table_define_index_column (int argc, VALUE *argv, VALUE self)
@@ -520,11 +508,11 @@ ruby_object_to_column_name (VALUE rb_name,
 }
 
 /*
- * call-seq:
- *   table.column(name) -> Groonga::Column or nil
- *
  * テーブルの _name_ に対応するカラムを返す。カラムが存在しな
  * い場合は +nil+ を返す。
+ *
+ * @overload column(name)
+ *   @return [Groonga::Column or nil]
  */
 VALUE
 rb_grn_table_get_column (VALUE self, VALUE rb_name)
@@ -601,11 +589,11 @@ rb_grn_table_get_column_surely (VALUE self, VALUE rb_name)
 }
 
 /*
- * call-seq:
- *   table.columns(name=nil) -> Groonga::Columnの配列
- *
  * テーブルの全てのカラムを返す。 _name_ が指定された場合はカ
  * ラム名の先頭が _name_ で始まるカラムを返す。
+ *
+ * @overload columns(name=nil)
+ *   @return [Groonga::Columnの配列]
  */
 static VALUE
 rb_grn_table_get_columns (int argc, VALUE *argv, VALUE self)
@@ -619,6 +607,7 @@ rb_grn_table_get_columns (int argc, VALUE *argv, VALUE self)
     VALUE rb_name, rb_columns;
     char *name = NULL;
     unsigned name_size = 0;
+    VALUE exception;
 
     rb_grn_table_deconstruct(SELF(self), &table, &context,
 			     NULL, NULL,
@@ -655,6 +644,13 @@ rb_grn_table_get_columns (int argc, VALUE *argv, VALUE self)
 	grn_table_cursor_get_key(context, cursor, &key);
 	column_id = key;
 	column = grn_ctx_at(context, *column_id);
+	exception = rb_grn_context_to_exception(context, self);
+	if (!NIL_P(exception)) {
+	    grn_table_cursor_close(context, cursor);
+	    grn_obj_unlink(context, columns);
+	    rb_exc_raise(exception);
+	}
+
 	rb_column = GRNOBJECT2RVAL(Qnil, context, column, GRN_FALSE);
 	rb_ary_push(rb_columns, rb_column);
     }
@@ -669,10 +665,9 @@ rb_grn_table_get_columns (int argc, VALUE *argv, VALUE self)
 }
 
 /*
- * call-seq:
- *   table.have_column?(name) -> true/false
- *
  * テーブルが _name_ カラムを持っている場合は +true+ を返す。
+ *
+ * @overload have_column?(name)
  */
 static VALUE
 rb_grn_table_have_column (VALUE self, VALUE rb_name)
@@ -762,54 +757,74 @@ rb_grn_table_open_grn_cursor (int argc, VALUE *argv, VALUE self,
 }
 
 /*
- * call-seq:
- *   table.open_cursor(options={}) -> Groonga::TableCursor
- *   table.open_cursor(options={}) {|cursor| }
- *
  * カーソルを生成して返す。ブロックを指定すると、そのブロッ
  * クに生成したカーソルが渡され、ブロックを抜けると自動的に
  * カーソルが破棄される。
  *
- * _options_に指定可能な値は以下の通り。
- * @param options [::Hash] The name and value
- *   pairs. Omitted names are initialized as the default value.
- * @option options :min The min
- *  キーの下限
- *
- * @option  options :max The max
- *  キーの上限
- *
- * @option options :offset The offset
- *   該当する範囲のレコードのうち、(0ベースで) _:offset_ 番目
- *   からレコードを取り出す。
- *
- * @option options :limit The limit
- *   該当する範囲のレコードのうち、 _:limit_ 件のみを取り出す。
- *   省略された場合または-1が指定された場合は、全件が指定され
- *   たものとみなす。
- *
- * @option options :order (asc) The order
- *   +:asc+ または +:ascending+ を指定すると昇順にレコードを取
- *   り出す。（デフォルト）
- *
- *   +:desc+ または +:descending+ を指定すると降順にレコードを
- *   取り出す。
- *
- * @option options :order_by The order_by
- *   +:id+ を指定するとID順にレコードを取り出す。（Arrayと
- *   Hashのデフォルト）
- *
- *   +:key+ 指定するとキー順にレコードを取り出す。ただし、
- *   Groonga::PatriciaTrieにしか使えない。（PatriciaTrieのデ
- *   フォルト）
- *
- * @option options :greater_than The greater_than
- *   +true+ を指定すると +:min+ で指定した値に一致した [ +key+ ] を
- *   範囲に含まない。
- *
- * @option options :less_than The less_than
- *   +true+ を指定すると +:max+ で指定した値に一致した [ +key+ ] を
- *   範囲に含まない。
+ * @overload open_cursor(options={})
+ *   @return [Groonga::TableCursor]
+ *   @param options [::Hash] The name and value
+ *     pairs. Omitted names are initialized as the default value.
+ *   @option options :min
+ *    キーの下限
+ *   @option options :max
+ *    キーの上限
+ *   @option options :offset
+ *     該当する範囲のレコードのうち、(0ベースで) _:offset_ 番目
+ *     からレコードを取り出す。
+ *   @option options :limit
+ *     該当する範囲のレコードのうち、 _:limit_ 件のみを取り出す。
+ *     省略された場合または-1が指定された場合は、全件が指定され
+ *     たものとみなす。
+ *   @option options :order (asc)
+ *     +:asc+ または +:ascending+ を指定すると昇順にレコードを取
+ *     り出す。（デフォルト）
+ *     +:desc+ または +:descending+ を指定すると降順にレコードを
+ *     取り出す。
+ *   @option options :order_by
+ *     +:id+ を指定するとID順にレコードを取り出す。（Arrayと
+ *     Hashのデフォルト）
+ *     +:key+ 指定するとキー順にレコードを取り出す。ただし、
+ *     Groonga::PatriciaTrieにしか使えない。（PatriciaTrieのデ
+ *     フォルト）
+ *   @option options :greater_than
+ *     +true+ を指定すると +:min+ で指定した値に一致した [ +key+ ] を
+ *     範囲に含まない。
+ *   @option options :less_than
+ *     +true+ を指定すると +:max+ で指定した値に一致した [ +key+ ] を
+ *     範囲に含まない。
+ * @overload open_cursor(options={})
+ *   @yield [cursor]
+ *   @param options [::Hash] The name and value
+ *     pairs. Omitted names are initialized as the default value.
+ *   @option options :min
+ *    キーの下限
+ *   @option options :max
+ *    キーの上限
+ *   @option options :offset
+ *     該当する範囲のレコードのうち、(0ベースで) _:offset_ 番目
+ *     からレコードを取り出す。
+ *   @option options :limit
+ *     該当する範囲のレコードのうち、 _:limit_ 件のみを取り出す。
+ *     省略された場合または-1が指定された場合は、全件が指定され
+ *     たものとみなす。
+ *   @option options :order (asc)
+ *     +:asc+ または +:ascending+ を指定すると昇順にレコードを取
+ *     り出す。（デフォルト）
+ *     +:desc+ または +:descending+ を指定すると降順にレコードを
+ *     取り出す。
+ *   @option options :order_by
+ *     +:id+ を指定するとID順にレコードを取り出す。（Arrayと
+ *     Hashのデフォルト）
+ *     +:key+ 指定するとキー順にレコードを取り出す。ただし、
+ *     Groonga::PatriciaTrieにしか使えない。（PatriciaTrieのデ
+ *     フォルト）
+ *   @option options :greater_than
+ *     +true+ を指定すると +:min+ で指定した値に一致した [ +key+ ] を
+ *     範囲に含まない。
+ *   @option options :less_than
+ *     +true+ を指定すると +:max+ で指定した値に一致した [ +key+ ] を
+ *     範囲に含まない。
  */
 static VALUE
 rb_grn_table_open_cursor (int argc, VALUE *argv, VALUE self)
@@ -828,11 +843,11 @@ rb_grn_table_open_cursor (int argc, VALUE *argv, VALUE self)
 }
 
 /*
- * call-seq:
- *   table.records -> Groonga::Recordの配列
- *
  * テーブルに登録されている全てのレコードが入っている配列を
  * 返す。
+ *
+ * @overload records
+ *   @return [Groonga::Recordの配列]
  */
 static VALUE
 rb_grn_table_get_records (int argc, VALUE *argv, VALUE self)
@@ -853,10 +868,10 @@ rb_grn_table_get_records (int argc, VALUE *argv, VALUE self)
 }
 
 /*
- * call-seq:
- *   table.size -> レコード数
- *
  * テーブルに登録されているレコード数を返す。
+ *
+ * @overload size
+ *   @return [Integer]
  */
 static VALUE
 rb_grn_table_get_size (VALUE self)
@@ -874,10 +889,9 @@ rb_grn_table_get_size (VALUE self)
 }
 
 /*
- * call-seq:
- *   table.empty? -> true/false
- *
  * テーブルにレコードが登録されていなければ +true+ を返す。
+ *
+ * @overload empty?
  */
 static VALUE
 rb_grn_table_empty_p (VALUE self)
@@ -895,10 +909,9 @@ rb_grn_table_empty_p (VALUE self)
 }
 
 /*
- * call-seq:
- *   table.truncate
- *
  * テーブルの全レコードを一括して削除する。
+ *
+ * @overload truncate
  */
 static VALUE
 rb_grn_table_truncate (VALUE self)
@@ -918,13 +931,17 @@ rb_grn_table_truncate (VALUE self)
 }
 
 /*
- * call-seq:
- *   table.each             {|record| } -> nil
- *   table.each(options={}) {|record| } -> nil
- *
  * テーブルに登録されているレコードを順番にブロックに渡す。
  *
- * _options_ is the same as #open_cursor's one.
+ * _options_ is the same as {#open_cursor} 's one.
+ *
+ * @overload each
+ *   @!macro [new] table.each.metadata
+ *     @yield [record]
+ *     @return [nil]
+ *   @!macro table.each.metadata
+ * @overload each(options={})
+ *   @!macro table.each.metadata
  */
 static VALUE
 rb_grn_table_each (int argc, VALUE *argv, VALUE self)
@@ -937,6 +954,8 @@ rb_grn_table_each (int argc, VALUE *argv, VALUE self)
     VALUE rb_cursor;
     grn_id id;
 
+    RETURN_ENUMERATOR(self, argc, argv);
+
     cursor = rb_grn_table_open_grn_cursor(argc, argv, self, &context);
     rb_cursor = GRNTABLECURSOR2RVAL(Qnil, context, cursor);
     rb_table = SELF(self);
@@ -951,10 +970,9 @@ rb_grn_table_each (int argc, VALUE *argv, VALUE self)
 }
 
 /*
- * call-seq:
- *   table.delete(id)
- *
  * テーブルの _id_ に対応するレコードを削除する。
+ *
+ * @overload delete(id)
  */
 VALUE
 rb_grn_table_delete (VALUE self, VALUE rb_id)
@@ -977,10 +995,7 @@ rb_grn_table_delete (VALUE self, VALUE rb_id)
 }
 
 /*
- * call-seq:
- *   table.sort(keys, options={}) -> Groonga::Recordの配列
- *
- * テーブルに登録されているレコードを_keys_で指定されたルー
+ * テーブルに登録されているレコードを _keys_ で指定されたルー
  * ルに従ってソートしたレコードの配列を返す。
  *
  * _order_ には +:asc+ ,  +:ascending+ , +:desc+ , +:descending+ の
@@ -1022,16 +1037,17 @@ rb_grn_table_delete (VALUE self, VALUE rb_id)
  * </pre>
  * =:
  *
- * @param options [::Hash] The name and value
- *   pairs. Omitted names are initialized as the default value.
- * @option options :offset The offset
- *   ソートされたレコードのうち、(0ベースで) _:offset_ 番目
- *   からレコードを取り出す。
- *
- * @option options :limit The limit
- *   ソートされたレコードのうち、 _:limit_ 件のみを取り出す。
- *   省略された場合または-1が指定された場合は、全件が指定され
- *   たものとみなす。
+ * @overload sort(keys, options={})
+ *   @param options [::Hash] The name and value
+ *     pairs. Omitted names are initialized as the default value.
+ *   @option options :offset
+ *     ソートされたレコードのうち、(0ベースで) _:offset_ 番目
+ *     からレコードを取り出す。
+ *   @option options :limit
+ *     ソートされたレコードのうち、 _:limit_ 件のみを取り出す。
+ *     省略された場合または-1が指定された場合は、全件が指定され
+ *     たものとみなす。
+ * @return [::Array<Groonga::Record>]
  */
 static VALUE
 rb_grn_table_sort (int argc, VALUE *argv, VALUE self)
@@ -1152,13 +1168,14 @@ rb_grn_table_sort (int argc, VALUE *argv, VALUE self)
 }
 
 /*
- * call-seq:
- *   table.group([key1, key2, ...], options={}) -> [Groonga::Hash, ...]
- *   table.group(key, options={}) -> Groonga::Hash
- *
  * _table_ のレコードを _key1_ , _key2_ , _..._ で指定したキーの
  * 値でグループ化する。多くの場合、キーにはカラムを指定する。
  * カラムはカラム名（文字列）でも指定可能。
+ *
+ * @overload group([key1, key2, ...], options={})
+ *   @return [[Groonga::Hash, ...]]
+ * @overload group(key, options={})
+ *   @return [Groonga::Hash]
  */
 static VALUE
 rb_grn_table_group (int argc, VALUE *argv, VALUE self)
@@ -1252,14 +1269,12 @@ rb_grn_table_group (int argc, VALUE *argv, VALUE self)
 }
 
 /*
- * Document-method: []
+ * _table_ の _id_ に対応する {Groonga::Record} を返す。
  *
- * call-seq:
- *   table[id] -> Groonga::Record
+ * 0.9.0から値ではなく {Groonga::Record} を返すようになった。
  *
- * _table_ の _id_ に対応するGroonga::Recordを返す。
- *
- * 0.9.0から値ではなくGroonga::Recordを返すようになった。
+ * @overload [](id)
+ *   @return [Groonga::Record]
  */
 VALUE
 rb_grn_table_array_reference (VALUE self, VALUE rb_id)
@@ -1294,17 +1309,16 @@ rb_grn_table_get_value (VALUE self, VALUE rb_id)
 }
 
 /*
- * Document-method: value
- *
- * call-seq:
- *   table.value(id) -> 値
- *   table.value(id, :id => true) -> 値
- *
  * _table_ の _id_ に対応する値を返す。
  *
- * <tt>:id => true</tt>が指定できるのは利便性のため。
- * Groonga::ArrayでもGroonga::HashやGroonga::PatriciaTrieと
+ * @:id => true@ が指定できるのは利便性のため。
+ * {Groonga::Array} でも {Groonga::Hash} や {Groonga::PatriciaTrie} と
  * 同じ引数で動くようになる。
+ *
+ * @overload value(id)
+ *   @return [値]
+ * @overload value(id, :id => true)
+ *   @return [値]
  */
 static VALUE
 rb_grn_table_get_value_convenience (int argc, VALUE *argv, VALUE self)
@@ -1354,18 +1368,15 @@ rb_grn_table_set_value (VALUE self, VALUE rb_id, VALUE rb_value)
 }
 
 /*
- * Document-method: set_value
- *
- * call-seq:
- *   table.set_value(id, value)
- *   table.set_value(id, value, :id => true)
- *
  * _table_ の _id_ に対応する値として _value_ 設定する。既存の値は
  * 上書きされる。
  *
- * <tt>:id => true</tt>が指定できるのは利便性のため。
- * Groonga::ArrayでもGroonga::HashやGroonga::PatriciaTrieと
+ * @:id => true@ が指定できるのは利便性のため。
+ * {Groonga::Array} でも {Groonga::Hash} や {Groonga::PatriciaTrie} と
  * 同じ引数で動くようになる。
+ *
+ * @overload set_value(id, value)
+ * @overload set_value(id, value, :id => true)
  */
 static VALUE
 rb_grn_table_set_value_convenience (int argc, VALUE *argv, VALUE self)
@@ -1407,17 +1418,16 @@ rb_grn_table_get_column_value (VALUE self, VALUE rb_id, VALUE rb_name)
 }
 
 /*
- * Document-method: column_value
- *
- * call-seq:
- *   table.column_value(id, name) -> 値
- *   table.column_value(id, name, :id => true) -> 値
- *
  * _table_ の _id_ に対応するカラム _name_ の値を返す。
  *
- * <tt>:id => true</tt>が指定できるのは利便性のため。
- * Groonga::ArrayでもGroonga::HashやGroonga::PatriciaTrieと
+ * @:id => true@ が指定できるのは利便性のため。
+ * {Groonga::Array} でも {Groonga::Hash} や {Groonga::PatriciaTrie} と
  * 同じ引数で動くようになる。
+ *
+ * @overload column_value(id, name)
+ *   @return [値]
+ * @overload column_value(id, name, :id => true)
+ *   @return [値]
  */
 static VALUE
 rb_grn_table_get_column_value_convenience (int argc, VALUE *argv, VALUE self)
@@ -1463,18 +1473,15 @@ rb_grn_table_set_column_value (VALUE self, VALUE rb_id,
 }
 
 /*
- * Document-method: set_column_value
- *
- * call-seq:
- *   table.set_column_value(id, name, value)
- *   table.set_column_value(id, name, value, :id => true)
- *
  * _table_ の _id_ に対応するカラム _name_ の値として _value_ 設定す
  * る。既存の値は上書きされる。
  *
- * <tt>:id => true</tt>が指定できるのは利便性のため。
- * Groonga::ArrayでもGroonga::HashやGroonga::PatriciaTrieと
+ * @:id => true@ が指定できるのは利便性のため。
+ * {Groonga::Array} でも {Groonga::Hash} や {Groonga::PatriciaTrie} と
  * 同じ引数で動くようになる。
+ *
+ * @overload set_column_value(id, name, value)
+ * @overload set_column_value(id, name, valuf, :id => true)
  */
 static VALUE
 rb_grn_table_set_column_value_convenience (int argc, VALUE *argv, VALUE self)
@@ -1500,18 +1507,14 @@ rb_grn_table_set_column_value_convenience (int argc, VALUE *argv, VALUE self)
 }
 
 /*
- * Document-method: unlock
- *
- * call-seq:
- *   table.unlock(options={})
- *
  * _table_ のロックを解除する。
  *
- * 利用可能なオプションは以下の通り。
- *
- * [ _:id_ ]
- *   _:id_ で指定したレコードのロックを解除する。（注:
- *   groonga側が未実装のため、現在は無視される）
+ * @overload unlock(options={})
+ *   @param options [::Hash] The name and value
+ *     pairs. Omitted names are initialized as the default value.
+ *   @option options :id
+ *     _:id_ で指定したレコードのロックを解除する。（注:
+ *     groonga側が未実装のため、現在は無視される）
  */
 static VALUE
 rb_grn_table_unlock (int argc, VALUE *argv, VALUE self)
@@ -1550,30 +1553,32 @@ rb_grn_table_unlock_ensure (VALUE self)
 }
 
 /*
- * Document-method: lock
- *
- * call-seq:
- *   table.lock(options={})
- *   table.lock(options={}) {}
- *
  * _table_ をロックする。ロックに失敗した場合は
- * Groonga::ResourceDeadlockAvoided例外が発生する。
+ * {Groonga::ResourceDeadlockAvoided} 例外が発生する。
  *
  * ブロックを指定した場合はブロックを抜けたときにunlockする。
  *
- * 利用可能なオプションは以下の通り。
- * @param options [::Hash] The name and value
- *   pairs. Omitted names are initialized as the default value.
- * @option options :timeout The timeout
- *
- *   ロックを獲得できなかった場合は _:timeout_ 秒間ロックの獲
- *   得を試みる。 _:timeout_ 秒以内にロックを獲得できなかった
- *   場合は例外が発生する。
- *
- * @option options :id The id
- *
- *   _:id_ で指定したレコードをロックする。（注: groonga側が
- *   未実装のため、現在は無視される）
+ * @overload lock(options={})
+ *   @param options [::Hash] The name and value
+ *     pairs. Omitted names are initialized as the default value.
+ *   @option options :timeout
+ *     ロックを獲得できなかった場合は _:timeout_ 秒間ロックの獲
+ *     得を試みる。 _:timeout_ 秒以内にロックを獲得できなかった
+ *     場合は例外が発生する。
+ *   @option options :id
+ *     _:id_ で指定したレコードをロックする。（注: groonga側が
+ *     未実装のため、現在は無視される）
+ * @overload lock(options={})
+ *   @yield ブロックを抜けたときにunlockする。
+ *   @param options [::Hash] The name and value
+ *     pairs. Omitted names are initialized as the default value.
+ *   @option options :timeout
+ *     ロックを獲得できなかった場合は _:timeout_ 秒間ロックの獲
+ *     得を試みる。 _:timeout_ 秒以内にロックを獲得できなかった
+ *     場合は例外が発生する。
+ *   @option options :id
+ *     _:id_ で指定したレコードをロックする。（注: groonga側が
+ *     未実装のため、現在は無視される）
  */
 static VALUE
 rb_grn_table_lock (int argc, VALUE *argv, VALUE self)
@@ -1615,22 +1620,16 @@ rb_grn_table_lock (int argc, VALUE *argv, VALUE self)
 }
 
 /*
- * Document-method: clear_lock
- *
- * call-seq:
- *   table.clear_lock(options={})
- *
  * _table_ のロックを強制的に解除する。
  *
- * 利用可能なオプションは以下の通り。
- * @param options [::Hash] The name and value
- *   pairs. Omitted names are initialized as the default value.
- * @option options :id The id
- *
- *   _:id_ で指定したレコードのロックを強制的に解除する。
- *   （注: groonga側が未実装のため、現在は無視される。実装さ
- *   れるのではないかと思っているが、実装されないかもしれな
- *   い。）
+ * @overload clear_lock(options={})
+ *   @param [::Hash] options The name and value
+ *     pairs. Omitted names are initialized as the default value.
+ *   @option options :id
+ *     _:id_ で指定したレコードのロックを強制的に解除する。
+ *     （注: groonga側が未実装のため、現在は無視される。実装さ
+ *     れるのではないかと思っているが、実装されないかもしれな
+ *     い。）
  */
 static VALUE
 rb_grn_table_clear_lock (int argc, VALUE *argv, VALUE self)
@@ -1660,22 +1659,16 @@ rb_grn_table_clear_lock (int argc, VALUE *argv, VALUE self)
 }
 
 /*
- * Document-method: locked?
- *
- * call-seq:
- *   table.locked?(options={})
- *
  * _table_ がロックされていれば +true+ を返す。
  *
- * 利用可能なオプションは以下の通り。
- * @param options [options] The name and value
- *   pairs. Omitted names are initialized as the default value.
- * @option options :id The id
- *
- *   _:id_ で指定したレコードがロックされていれば +true+ を返す。
- *   （注: groonga側が未実装のため、現在は無視される。実装さ
- *   れるのではないかと思っているが、実装されないかもしれな
- *   い。）
+ * @overload locked?(options={})
+ *   @param [options] options The name and value
+ *     pairs. Omitted names are initialized as the default value.
+ *   @option options :id
+ *     _:id_ で指定したレコードがロックされていれば +true+ を返す。
+ *     （注: groonga側が未実装のため、現在は無視される。実装さ
+ *     れるのではないかと思っているが、実装されないかもしれな
+ *     い。）
  */
 static VALUE
 rb_grn_table_is_locked (int argc, VALUE *argv, VALUE self)
@@ -1703,16 +1696,11 @@ rb_grn_table_is_locked (int argc, VALUE *argv, VALUE self)
 }
 
 /*
- * call-seq:
- *   table.select(options) {|record| ...} -> Groonga::Hash
- *   table.select(query, options) -> Groonga::Hash
- *   table.select(expression, options) -> Groonga::Hash
- *
  * _table_ からブロックまたは文字列で指定した条件にマッチする
  * レコードを返す。返されたテーブルには +expression+ という特
  * 異メソッドがあり、指定した条件を表している
- * Groonga::Expressionを取得できる。
- * Groonga::Expression#snippetを使うことにより、指定した条件
+ * {Groonga::Expression} を取得できる。
+ * {Groonga::Expression#snippet} を使うことにより、指定した条件
  * 用のスニペットを簡単に生成できる。
  *
  * <pre>
@@ -1741,108 +1729,104 @@ rb_grn_table_is_locked (int argc, VALUE *argv, VALUE self)
  * ---
  * </pre>
  *
- * _query_ には「[カラム名]:[演算子][値]」という書式で条件を
- * 指定する。演算子は以下の通り。
- *
- * - なし := [カラム値] == [値]
- * - @!@ := [カラム値] != [値]
- * - @<@ := [カラム値] < [値]
- * - @>@ := [カラム値] > [値]
- * - @<=@ := [カラム値] <= [値]
- * - @>=@ := [カラム値] >= [値]
- * - @@@ := [カラム値]が[値]を含んでいるかどうか
- *
- * 例:
- *
- * <pre>
- * !!!ruby
- * "name:daijiro" # "name"カラムの値が"daijiro"のレコードにマッチ
- * "description:@groonga" # "description"カラムが
- *                        # "groonga"を含んでいるレコードにマッチ
- * </pre>
- *
- * _expression_ には既に作成済みのGroonga::Expressionを渡す
- *
- * ブロックで条件を指定する場合は
- * Groonga::RecordExpressionBuilderを参照。
- *
- * Ruby1.9以降では、ブロックで条件を指定する際に
- * Groonga::ColumnExpressionBuilderの他に"!="も使用可能。
- *
- * 例:
- *
- * <pre>
- * !!!ruby
- * comments = Groonga::Array.create(:name => "Comments")
- * comments.define_column("content", "Text")
- * comments.add(:content => "Hello Good-bye!")
- * comments.add(:content => "Hello World")
- * comments.add(:content => "test")
- * result = comments.select do |record|
- *   record.content != "test"
- * end
- * p result.collect {|record| record.content}
- *   # => ["Hello Good-bye!", "Hello World"]
- * </pre>
- *
- * _options_ に指定可能な値は以下の通り。
- * @param options [::Hash] The name and value
- *   pairs. Omitted names are initialized as the default value.
- * @option options :default_column
- *
- *   "column_name:hoge"ではなく"hoge"のようにcolumn_nameが指
- *   定されない条件の検索対象となるカラムを指定する。
- *
- * @option options :operator (Groonga::Operator::OR) The operator
- *
- *   マッチしたレコードをどのように扱うか。指定可能な値は以
- *   下の通り。省略した場合はGroonga::Operator::OR。
- *
- *   [Groonga::Operator::OR] マッチしたレコードを追加。すで
- *                           にレコードが追加されている場合
- *                           は何もしない。
- *   [Groonga::Operator::AND] マッチしたレコードのスコアを増
- *                            加。マッチしなかったレコード
- *                            を削除。
- *   [Groonga::Operator::BUT] マッチしたレコードを削除。
- *   [Groonga::Operator::ADJUST] マッチしたレコードのスコア
- *                               を増加。
- *
- * @option options :result The result
- *
- *   検索結果を格納するテーブル。マッチしたレコードが追加さ
- *   れていく。省略した場合は新しくテーブルを作成して返す。
- *
- * @option options :name The name
- *
- *   条件の名前。省略した場合は名前を付けない。
- *
- * @option options :syntax The syntax
- *
- *   _query_ の構文。省略した場合は +:query+ 。
- *
- *   参考: Groonga::Expression#parse.
- *
- * @option options :allow_pragma The allow_pragma
- *
- *   query構文時にプラグマを利用するかどうか。省略した場合は
- *   利用する。
- *
- *   参考: Groonga::Expression#parse.
- *
- * @option options :allow_column The allow_column
- *
- *   query構文時にカラム指定を利用するかどうか。省略した場合
- *   は利用する。
- *
- *   参考: Groonga::Expression#parse.
- *
- * @option options :allow_update The allow_update
- *
- *   script構文時に更新操作を利用するかどうか。省略した場合
- *   は利用する。
- *
- *   参考: Groonga::Expression#parse.
+ * @overload select(options)
+ *   @yield [record] ブロックで条件を指定する場合は
+ *     Groonga::RecordExpressionBuilderを参照。
+ *
+ *     Ruby1.9以降では、ブロックで条件を指定する際に
+ *     Groonga::ColumnExpressionBuilderの他に"!="も使用可能。
+ *
+ *     例:
+ *
+ *     <pre>
+ *     !!!ruby
+ *     comments = Groonga::Array.create(:name => "Comments")
+ *     comments.define_column("content", "Text")
+ *     comments.add(:content => "Hello Good-bye!")
+ *     comments.add(:content => "Hello World")
+ *     comments.add(:content => "test")
+ *     result = comments.select do |record|
+ *       record.content != "test"
+ *     end
+ *     p result.collect {|record| record.content}
+ *       # => ["Hello Good-bye!", "Hello World"]
+ *     </pre>
+ *
+ *   @!macro [new] table.select.options
+ *     @param options [::Hash] The name and value
+ *       pairs. Omitted names are initialized as the default value.
+ *     @option options :default_column
+ *       "column_name:hoge"ではなく"hoge"のようにcolumn_nameが指
+ *       定されない条件の検索対象となるカラムを指定する。
+ *     @option options :operator (Groonga::Operator::OR)
+ *       マッチしたレコードをどのように扱うか。指定可能な値は以
+ *       下の通り。省略した場合はGroonga::Operator::OR。
+ *
+ *       - Groonga::Operator::OR :=
+ *         マッチしたレコードを追加。すでにレコードが追加されている場合
+ *         は何もしない。 =:
+ *       - Groonga::Operator::AND :=
+ *         マッチしたレコードのスコアを増加。マッチしなかったレコードを削除。 =:
+ *       - Groonga::Operator::BUT :=
+ *         マッチしたレコードを削除。 =:
+ *       - Groonga::Operator::ADJUST :=
+ *         マッチしたレコードのスコアを増加。 =:
+ *
+ *     @option options :result
+ *       検索結果を格納するテーブル。マッチしたレコードが追加さ
+ *       れていく。省略した場合は新しくテーブルを作成して返す。
+ *     @option options :name
+ *       条件の名前。省略した場合は名前を付けない。
+ *     @option options :syntax
+ *       _query_ の構文。省略した場合は +:query+ 。
+ *
+ *       参考: {Groonga::Expression#parse} .
+ *
+ *     @option options :allow_pragma
+ *       query構文時にプラグマを利用するかどうか。省略した場合は
+ *       利用する。
+ *
+ *       参考: {Groonga::Expression#parse} .
+ *
+ *     @option options :allow_column
+ *       query構文時にカラム指定を利用するかどうか。省略した場合
+ *       は利用する。
+ *
+ *       参考: {Groonga::Expression#parse} .
+ *
+ *     @option options :allow_update
+ *       script構文時に更新操作を利用するかどうか。省略した場合
+ *       は利用する。
+ *
+ *     参考: {Groonga::Expression#parse} .
+ *
+ * @overload select(query, options)
+ *   _query_ には「[カラム名]:[演算子][値]」という書式で条件を
+ *   指定する。演算子は以下の通り。
+ *
+ *   - なし := [カラム値] == [値]
+ *   - @!@ := [カラム値] != [値]
+ *   - @<@ := [カラム値] < [値]
+ *   - @>@ := [カラム値] > [値]
+ *   - @<=@ := [カラム値] <= [値]
+ *   - @>=@ := [カラム値] >= [値]
+ *   - @@@ := [カラム値]が[値]を含んでいるかどうか
+ *
+ *   例:
+ *
+ *   <pre>
+ *   !!!ruby
+ *   "name:daijiro" # "name"カラムの値が"daijiro"のレコードにマッチ
+ *   "description:@groonga" # "description"カラムが
+ *                          # "groonga"を含んでいるレコードにマッチ
+ *   </pre>
+ *
+ *   @!macro table.select.options
+ * @overload select(expression, options)
+ *   _expression_ には既に作成済みの {Groonga::Expression} を渡す。
+ *
+ *   @!macro table.select.options
+ * @return [Groonga::Hash]
  */
 static VALUE
 rb_grn_table_select (int argc, VALUE *argv, VALUE self)
@@ -1852,7 +1836,7 @@ rb_grn_table_select (int argc, VALUE *argv, VALUE self)
     grn_operator operator = GRN_OP_OR;
     VALUE rb_query = Qnil, condition_or_options, options;
     VALUE rb_name, rb_operator, rb_result, rb_syntax;
-    VALUE rb_allow_pragma, rb_allow_column, rb_allow_update;
+    VALUE rb_allow_pragma, rb_allow_column, rb_allow_update, rb_allow_leading_not;
     VALUE rb_default_column;
     VALUE rb_expression = Qnil, builder;
 
@@ -1886,6 +1870,7 @@ rb_grn_table_select (int argc, VALUE *argv, VALUE self)
 			"allow_pragma", &rb_allow_pragma,
 			"allow_column", &rb_allow_column,
 			"allow_update", &rb_allow_update,
+			"allow_leading_not", &rb_allow_leading_not,
 			"default_column", &rb_default_column,
 			NULL);
 
@@ -1909,6 +1894,7 @@ rb_grn_table_select (int argc, VALUE *argv, VALUE self)
       rb_funcall(builder, rb_intern("allow_pragma="), 1, rb_allow_pragma);
       rb_funcall(builder, rb_intern("allow_column="), 1, rb_allow_column);
       rb_funcall(builder, rb_intern("allow_update="), 1, rb_allow_update);
+      rb_funcall(builder, rb_intern("allow_leading_not="), 1, rb_allow_leading_not);
       rb_funcall(builder, rb_intern("default_column="), 1, rb_default_column);
       rb_expression = rb_grn_record_expression_builder_build(builder);
     }
@@ -1952,12 +1938,11 @@ rb_grn_table_set_operation_bang (VALUE self, VALUE rb_other,
 }
 
 /*
- * call-seq:
- *   table.union!(other) -> Groonga::Table
- *
  * キーを比較し、 _table_ には登録されていない _other_ のレコー
  * ドを _table_ に作成する。
  *
+ * @overload union!(other)
+ *   @return [Groonga::Table]
  */
 static VALUE
 rb_grn_table_union_bang (VALUE self, VALUE rb_other)
@@ -1967,12 +1952,11 @@ rb_grn_table_union_bang (VALUE self, VALUE rb_other)
 
 
 /*
- * call-seq:
- *   table.intersection!(other) -> Groonga::Table
- *
  * キーを比較し、 _other_ には登録されていないレコードを
  * _table_ から削除する。
  *
+ * @overload intersection!(other)
+ *   @return [Groonga::Table]
  */
 static VALUE
 rb_grn_table_intersection_bang (VALUE self, VALUE rb_other)
@@ -1981,12 +1965,11 @@ rb_grn_table_intersection_bang (VALUE self, VALUE rb_other)
 }
 
 /*
- * call-seq:
- *   table.difference!(other) -> Groonga::Table
- *
  * キーを比較し、 _other_ にも登録されているレコードを _table_
  * から削除する。
  *
+ * @overload difference!(other)
+ *   @return [Groonga::Table]
  */
 static VALUE
 rb_grn_table_difference_bang (VALUE self, VALUE rb_other)
@@ -1995,12 +1978,11 @@ rb_grn_table_difference_bang (VALUE self, VALUE rb_other)
 }
 
 /*
- * call-seq:
- *   table.merge!(other) -> Groonga::Table
- *
  * キーを比較し、 _other_ にも登録されている _table_ のレコード
  * のスコアを _other_ のスコアと同値にする。
  *
+ * @overload merge!(other)
+ *   @return [Groonga::Table]
  */
 static VALUE
 rb_grn_table_merge_bang (VALUE self, VALUE rb_other)
@@ -2009,11 +1991,10 @@ rb_grn_table_merge_bang (VALUE self, VALUE rb_other)
 }
 
 /*
- * call-seq:
- *   table.support_key? -> true/false
- *
  * _table_ に主キーが設定されていれば +true+ 、されていなければ
  * +false+ を返す。
+ *
+ * @overload support_key?
  */
 static VALUE
 rb_grn_table_support_key_p (VALUE self)
@@ -2022,12 +2003,11 @@ rb_grn_table_support_key_p (VALUE self)
 }
 
 /*
- * call-seq:
- *   table.support_sub_records? -> true/false
- *
  * グループ化したとき、テーブルにグループに含まれるレコード
  * 数を格納できる場合は +true+ 、格納できない場合は +false+ を返
  * す。
+ *
+ * @overload support_sub_records?
  */
 static VALUE
 rb_grn_table_support_sub_records_p (VALUE self)
@@ -2042,14 +2022,13 @@ rb_grn_table_support_sub_records_p (VALUE self)
 }
 
 /*
- * call-seq:
- *   table.exist?(id) -> true/false
- *
  * _table_ に _id_ で指定したIDのレコードが存在する場合は +true+ 、
  * 存在しない場合は +false+ を返す。
  *
  * 注意: 実行には相応のコストがかかるのであまり頻繁に呼ばな
  * いようにして下さい。
+ *
+ * @overload exist?(id)
  */
 static VALUE
 rb_grn_table_exist_p (VALUE self, VALUE id)
@@ -2065,18 +2044,16 @@ rb_grn_table_exist_p (VALUE self, VALUE id)
 }
 
 /*
- * Document-method: defrag
- *
- * call-seq:
- *   table.defrag(options={}) -> n_segments
- *
  * Defrags all variable size columns in the table.
  *
+ * @overload defrag(options={})
+ *   @param options [::Hash] The name and value
+ *     pairs. Omitted names are initialized as the default value.
+ *   @option options [Integer] :threshold (0) the threshold to
+ *     determine whether a segment is defraged. Available
+ *     values are -4..22. -4 means all segments are defraged.
+ *     22 means no segment is defraged.
  * @return [Integer] the number of defraged segments
- * @option options [Integer] :threshold (0) the threshold to
- *   determine whether a segment is defraged. Available
- *   values are -4..22. -4 means all segments are defraged.
- *   22 means no segment is defraged.
  * @since 1.3.0
  */
 static VALUE
@@ -2107,15 +2084,11 @@ rb_grn_table_defrag (int argc, VALUE *argv, VALUE self)
 }
 
 /*
- * Document-method: rename
- *
- * call-seq:
- *   table.rename(name)
- *
  * Renames the table to name.
  *
- * @param name [String] the new name
- * @since 1.3.0
+ * @overload rename(name)
+ *   @param name [String] the new name
+ *   @since 1.3.0
  */
 static VALUE
 rb_grn_table_rename (VALUE self, VALUE rb_name)