ext/groonga/rb-grn-column.c in rroonga-2.0.4 vs ext/groonga/rb-grn-column.c in rroonga-2.0.5
- old
+ new
@@ -165,117 +165,213 @@
xfree(name);
return rb_name;
}
-/*
- * call-seq:
- * column.select(options) {|record| ...} -> Groonga::Hash
- * column.select(query, options) -> Groonga::Hash
- * column.select(expression, options) -> Groonga::Hash
- *
+ /*
* カラムが所属するテーブルからブロックまたは文字列で指定し
* た条件にマッチするレコードを返す。返されたテーブルには
* +expression+ という特異メソッドがあり、指定した条件を表し
* ているGroonga::Expressionを取得できる。
* Groonga::Expression#snippetを使うことにより、指定した条件
* 用のスニペットを簡単に生成できる。
*
* bc. !!!ruby
- * results = description_column.select do |column|
- * column =~ "groonga"
- * end
- * snippet = results.expression.snippet([["<em>", "</em>"]])
- * results.each do |record|
- * puts "#{record['name']}の説明文の中で「groonga」が含まれる部分"
- * snippet.execute(record["description"]).each do |snippet|
- * puts "---"
- * puts "#{snippet}..."
- * puts "---"
+ * results = description_column.select do |column|
+ * column =~ "groonga"
* end
- * end
+ * snippet = results.expression.snippet([["<em>", "</em>"]])
+ * results.each do |record|
+ * puts "#{record['name']}の説明文の中で「groonga」が含まれる部分"
+ * snippet.execute(record["description"]).each do |snippet|
+ * puts "---"
+ * puts "#{snippet}..."
+ * puts "---"
+ * end
+ * end
*
* 出力例
+ * <pre>
+ * rroongaの説明文の中で「groonga」が含まれる部分
+ * ---
+ * rroongaは<em>groonga</em>のいわゆるDB-APIの層の...
+ * ---
*
- * pre. rroongaの説明文の中で「groonga」が含まれる部分
- * ---
- * rroongaは<em>groonga</em>のいわゆるDB-APIの層の...
- * ---
+ * @return [Groonga::Hash] 検索結果
+ * @overload select(options)
+ * @yieldparam [Groonga::Record] record
+ * @param [::Hash] options The name and value
+ * pairs. Omitted names are initialized as the default value.
+ * @option options :operator (Groonga::Operator::OR)
+ * マッチしたレコードをどのように扱うか。指定可能な値は以
+ * 下の通り。
*
- * _query_ には「[カラム名]:[演算子][値]」という書式で条件を
- * 指定する。演算子は以下の通り。
+ * [Groonga::Operator::OR]
+ * マッチしたレコードを追加。すでにレコードが追加され
+ * ている場合は何もしない。
+ * [Groonga::Operator::AND]
+ * マッチしたレコードのスコアを増加。マッチしなかった
+ * レコードを削除。
+ * [Groonga::Operator::BUT]
+ * マッチしたレコードを削除。
+ * [Groonga::Operator::ADJUST]
+ * マッチしたレコードのスコアを増加。
*
- * - なし := [カラム値] == [値]
- * - @!@ := [カラム値] != [値]
- * - @<@ := [カラム値] < [値]
- * - @>@ := [カラム値] > [値]
- * - @<=@ := [カラム値] <= [値]
- * - @>=@ := [カラム値] >= [値]
- * - @@@ := [カラム値]が[値]を含んでいるかどうか
+ * @option options :result
+ * 検索結果を格納するテーブル。マッチしたレコードが追加さ
+ * れていく。省略した場合は新しくテーブルを作成して返す。
*
- * 例:
+ * @option options :name
+ * 条件の名前。省略した場合は名前を付けない。
*
- * - @"groonga"@ := _column_ カラムの値が @"groonga"@ のレコードにマッチ
- * - @"name:daijiro"@ :=
- * _column_ カラムが属しているテーブルの @"name"@ カラムの値が
- * @"daijiro"@ のレコードにマッチ =:
- * - @"description:@@@groonga"@ :=
- * _column_ カラムが属しているテーブルの @"description"@ カラムが
- * @"groonga"@ を含んでいるレコードにマッチ =:
+ * @option options :syntax (:query)
+ * _query_ の構文。
*
- * _expression_ には既に作成済みのGroonga::Expressionを渡す
+ * 参考: Groonga::Expression#parse.
*
- * ブロックで条件を指定する場合は
- * {Groonga::ColumnExpressionBuilder} を参照。
+ * @option options :allow_pragma
+ * query構文時にプラグマを利用するかどうか。省略した場合は
+ * 利用する。
*
- * _options_ に指定可能な値は以下の通り。
- * @param [::Hash] options The name and value
- * pairs. Omitted names are initialized as the default value.
- * @option options :operator (Groonga::Operator::OR) The operator
- * マッチしたレコードをどのように扱うか。指定可能な値は以
- * 下の通り。
+ * 参考: Groonga::Expression#parse.
*
- * [Groonga::Operator::OR]
+ * @option options :allow_column The allow_column
+ * query構文時にカラム指定を利用するかどうか。省略した場合
+ * は利用する。
+ *
+ * 参考: Groonga::Expression#parse.
+ *
+ * @option options :allow_update
+ * script構文時に更新操作を利用するかどうか。省略した場合
+ * は利用する。
+ *
+ * 参考: Groonga::Expression#parse.
+ *
+ * @overload select(query, options)
+ * @param [String] query 条件の指定
+ * _query_ には「[カラム名]:[演算子][値]」という書式で条件を
+ * 指定する。演算子は以下の通り。
+ *
+ * - なし := [カラム値] == [値]
+ * - @!@ := [カラム値] != [値]
+ * - @<@ := [カラム値] < [値]
+ * - @>@ := [カラム値] > [値]
+ * - @<=@ := [カラム値] <= [値]
+ * - @>=@ := [カラム値] >= [値]
+ * - @@@ := [カラム値]が[値]を含んでいるかどうか
+ *
+ * 例:
+ *
+ * - @"groonga"@ := _column_ カラムの値が @"groonga"@ のレコードにマッチ
+ * - @"name:daijiro"@ :=
+ * _column_ カラムが属しているテーブルの @"name"@ カラムの値が
+ * @"daijiro"@ のレコードにマッチ =:
+ * - @"description:@@@groonga"@ :=
+ * _column_ カラムが属しているテーブルの @"description"@ カラムが
+ * @"groonga"@ を含んでいるレコードにマッチ =:
+ *
+ * @param [::Hash] options The name and value
+ * pairs. Omitted names are initialized as the default value.
+ * @option options :operator (Groonga::Operator::OR)
+ * マッチしたレコードをどのように扱うか。指定可能な値は以
+ * 下の通り。
+ *
+ * [Groonga::Operator::OR]
* マッチしたレコードを追加。すでにレコードが追加され
* ている場合は何もしない。
- * [Groonga::Operator::AND]
+ * [Groonga::Operator::AND]
* マッチしたレコードのスコアを増加。マッチしなかった
* レコードを削除。
- * [Groonga::Operator::BUT]
+ * [Groonga::Operator::BUT]
* マッチしたレコードを削除。
- * [Groonga::Operator::ADJUST]
+ * [Groonga::Operator::ADJUST]
* マッチしたレコードのスコアを増加。
*
- * @option options :result The result
- * 検索結果を格納するテーブル。マッチしたレコードが追加さ
- * れていく。省略した場合は新しくテーブルを作成して返す。
+ * @option options :result
+ * 検索結果を格納するテーブル。マッチしたレコードが追加さ
+ * れていく。省略した場合は新しくテーブルを作成して返す。
*
- * @option options :name The name
- * 条件の名前。省略した場合は名前を付けない。
+ * @option options :name
+ * 条件の名前。省略した場合は名前を付けない。
*
- * @option options :syntax (:query) The syntax
- * _query_の構文。
+ * @option options :syntax (:query)
+ * _query_ の構文。
*
- * 参考: Groonga::Expression#parse.
+ * 参考: Groonga::Expression#parse.
*
- * @option options :allow_pragma The allow_pragma
- * query構文時にプラグマを利用するかどうか。省略した場合は
- * 利用する。
+ * @option options :allow_pragma
+ * query構文時にプラグマを利用するかどうか。省略した場合は
+ * 利用する。
*
- * 参考: Groonga::Expression#parse.
+ * 参考: Groonga::Expression#parse.
*
- * @option options :allow_column The allow_column
- * query構文時にカラム指定を利用するかどうか。省略した場合
- * は利用する。
+ * @option options :allow_column The allow_column
+ * query構文時にカラム指定を利用するかどうか。省略した場合
+ * は利用する。
*
- * 参考: Groonga::Expression#parse.
+ * 参考: Groonga::Expression#parse.
*
- * @option options :allow_update
- * script構文時に更新操作を利用するかどうか。省略した場合
- * は利用する。
+ * @option options :allow_update
+ * script構文時に更新操作を利用するかどうか。省略した場合
+ * は利用する。
*
- * 参考: Groonga::Expression#parse.
+ * 参考: Groonga::Expression#parse.
+ *
+ * @overload select(expression, options)
+ * @param [Groonga::Expression] expression 条件を表すオブジェクト
+ * _expression_ には既に作成済みのGroonga::Expressionを渡す
+ *
+ * ブロックで条件を指定する場合は
+ * {Groonga::ColumnExpressionBuilder} を参照。
+ *
+ * @param [::Hash] options The name and value
+ * pairs. Omitted names are initialized as the default value.
+ * @option options :operator (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 The allow_column
+ * query構文時にカラム指定を利用するかどうか。省略した場合
+ * は利用する。
+ *
+ * 参考: Groonga::Expression#parse.
+ *
+ * @option options :allow_update
+ * script構文時に更新操作を利用するかどうか。省略した場合
+ * は利用する。
+ *
+ * 参考: Groonga::Expression#parse.
+ *
*/
static VALUE
rb_grn_column_select (int argc, VALUE *argv, VALUE self)
{
grn_ctx *context;
@@ -357,22 +453,16 @@
return rb_result;
}
/*
- * Document-method: unlock
- *
- * call-seq:
- * column.unlock(options={})
- *
* _column_ のロックを解除する。
- *
- * 利用可能なオプションは以下の通り。
- *
- * [_:id_]
- * _:id_ で指定したレコードのロックを解除する。
- * （注: groonga側が未実装のため、現在は無視される）
+ * @overload unlock(options={})
+ * @param [::Hash] options 利用可能なオプションは以下の通り。
+ * @option options :id
+ * _:id_ で指定したレコードのロックを解除する。
+ * （注: groonga側が未実装のため、現在は無視される）
*/
static VALUE
rb_grn_column_unlock (int argc, VALUE *argv, VALUE self)
{
grn_id id = GRN_ID_NIL;
@@ -406,30 +496,32 @@
{
return rb_grn_column_unlock(0, NULL, self);
}
/*
- * Document-method: lock
- *
- * call-seq:
- * column.lock(options={})
- * column.lock(options={}) {...}
- *
* _column_ をロックする。ロックに失敗した場合は
* Groonga::ResourceDeadlockAvoided例外が発生する。
*
- * ブロックを指定した場合はブロックを抜けたときにunlockする。
- *
- * 利用可能なオプションは以下の通り。
- *
- * [_:timeout_]
- * ロックを獲得できなかった場合は_:timeout_秒間ロックの獲
- * 得を試みる。_:timeout_秒以内にロックを獲得できなかった
- * 場合は例外が発生する。
- * [_:id_]
- * _:id_で指定したレコードをロックする。（注: groonga側が
- * 未実装のため、現在は無視される）
+ * @overload lock(options={})
+ * @param [::Hash] options 利用可能なオプションは以下の通り。
+ * @option options :timeout
+ * ロックを獲得できなかった場合は _:timeout_ 秒間ロックの獲
+ * 得を試みる。 _:timeout_ 秒以内にロックを獲得できなかった
+ * 場合は例外が発生する。
+ * @option options :id
+ * _:id_で指定したレコードをロックする。（注: groonga側が
+ * 未実装のため、現在は無視される）
+ * @overload lock(options={})
+ * @yield ブロックを指定した場合はブロックを抜けたときにunlockする。
+ * @param [::Hash] options 利用可能なオプションは以下の通り。
+ * @option options :timeout
+ * ロックを獲得できなかった場合は _:timeout_秒間ロックの獲
+ * 得を試みる。 _:timeout_秒以内にロックを獲得できなかった
+ * 場合は例外が発生する。
+ * @option options :id
+ * _:id_で指定したレコードをロックする。（注: groonga側が
+ * 未実装のため、現在は無視される）
*/
static VALUE
rb_grn_column_lock (int argc, VALUE *argv, VALUE self)
{
grn_id id = GRN_ID_NIL;
@@ -466,24 +558,18 @@
return Qnil;
}
}
/*
- * Document-method: clear_lock
- *
- * call-seq:
- * column.clear_lock(options={})
- *
- * _column_のロックを強制的に解除する。
- *
- * 利用可能なオプションは以下の通り。
- *
- * [_:id_]
- * _:id_で指定したレコードのロックを強制的に解除する。
- * （注: groonga側が未実装のため、現在は無視される。実装さ
- * れるのではないかと思っているが、実装されないかもしれな
- * い。）
+ * _column_ のロックを強制的に解除する。
+ * @overload clear_lock(options={})
+ * @param [::Hash] options 利用可能なオプションは以下の通り。
+ * @option options :id
+ * _:id_で指定したレコードのロックを強制的に解除する。
+ * （注: groonga側が未実装のため、現在は無視される。実装さ
+ * れるのではないかと思っているが、実装されないかもしれな
+ * い。）
*/
static VALUE
rb_grn_column_clear_lock (int argc, VALUE *argv, VALUE self)
{
grn_id id = GRN_ID_NIL;
@@ -508,24 +594,18 @@
return Qnil;
}
/*
- * Document-method: locked?
- *
- * call-seq:
- * column.locked?(options={})
- *
* _column_ がロックされていれば +true+ を返す。
- *
- * 利用可能なオプションは以下の通り。
- *
- * [_:id_]
- * _:id_で指定したレコードがロックされていれば +true+ を返す。
- * （注: groonga側が未実装のため、現在は無視される。実装さ
- * れるのではないかと思っているが、実装されないかもしれな
- * い。）
+ * @overload locked?(options={})
+ * @param [::Hash] options 利用可能なオプションは以下の通り。
+ * @option options :id
+ * _:id_で指定したレコードがロックされていれば +true+ を返す。
+ * （注: groonga側が未実装のため、現在は無視される。実装さ
+ * れるのではないかと思っているが、実装されないかもしれな
+ * い。）
*/
static VALUE
rb_grn_column_is_locked (int argc, VALUE *argv, VALUE self)
{
grn_id id = GRN_ID_NIL;
@@ -680,18 +760,15 @@
return Qfalse;
}
}
/*
- * Document-method: indexes
- *
- * call-seq:
- * column.indexes(operator=Groonga::Operator::MATCH) -> [index_column, ...]
- *
- * _operation_ を実行できる _column_ のインデックスを返す。
- *
+ * _operator_ を実行できる _column_ のインデックスを返す。
* @since 1.0.9
+ * @return [Array<index_column>] _operator_ を実行できる _column_ のインデックス
+ * @overload indexes(operator=Groonga::Operator::MATCH)
+ * @param [Groonga::Operator::XXX] operator
*/
static VALUE
rb_grn_column_get_indexes (int argc, VALUE *argv, VALUE self)
{
grn_ctx *context;
@@ -729,18 +806,13 @@
xfree(indexes);
return rb_indexes;
}
/*
- * 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
*/
static VALUE
rb_grn_column_rename (VALUE self, VALUE rb_name)
{
int rc;