[ruby-oci8-commit] [533] trunk/ruby-oci8: revise yard comment.
nobody at rubyforge.org
nobody at rubyforge.org
Sun Aug 12 12:04:39 UTC 2012
Revision: 533
Author: kubo
Date: 2012-08-12 12:04:38 +0000 (Sun, 12 Aug 2012)
Log Message:
-----------
revise yard comment.
Modified Paths:
--------------
trunk/ruby-oci8/ChangeLog
trunk/ruby-oci8/ext/oci8/stmt.c
trunk/ruby-oci8/lib/oci8/cursor.rb
Modified: trunk/ruby-oci8/ChangeLog
===================================================================
--- trunk/ruby-oci8/ChangeLog 2012-08-11 14:22:30 UTC (rev 532)
+++ trunk/ruby-oci8/ChangeLog 2012-08-12 12:04:38 UTC (rev 533)
@@ -1,3 +1,6 @@
+2012-08-12 KUBO Takehiro <kubo at jiubao.org>
+ * ext/oci8/stmt.c, lib/oci8/cursor.rb: revise yard comment.
+
2012-08-11 KUBO Takehiro <kubo at jiubao.org>
* ext/oci8/stmt.c, lib/oci8/cursor.rb: refactor OCI8::Cursor to simplify
C code.
Modified: trunk/ruby-oci8/ext/oci8/stmt.c
===================================================================
--- trunk/ruby-oci8/ext/oci8/stmt.c 2012-08-11 14:22:30 UTC (rev 532)
+++ trunk/ruby-oci8/ext/oci8/stmt.c 2012-08-12 12:04:38 UTC (rev 533)
@@ -41,6 +41,15 @@
sizeof(oci8_stmt_t),
};
+/*
+ * call-seq:
+ * __initialize(connection, sql_statement)
+ *
+ * @param [OCI8] connection
+ * @param [String] sql_statement
+ *
+ * @private
+ */
static VALUE oci8_stmt_initialize(VALUE self, VALUE svc, VALUE sql)
{
oci8_stmt_t *stmt = DATA_PTR(self);
@@ -78,6 +87,15 @@
return Qnil;
}
+/*
+ * call-seq:
+ * __define(position, bindobj)
+ *
+ * @param [Integer] position
+ * @param [OCI8::BindType::Base] bindobj
+ *
+ * @private
+ */
static VALUE oci8_define_by_pos(VALUE self, VALUE vposition, VALUE vbindobj)
{
oci8_stmt_t *stmt = TO_STMT(self);
@@ -110,6 +128,15 @@
return obind->base.self;
}
+/*
+ * call-seq:
+ * __bind(placeholder, bindobj)
+ *
+ * @param [Integer, String or Symbol] placeholder
+ * @param [OCI8::BindType::Base] bindobj
+ *
+ * @private
+ */
static VALUE oci8_bind(VALUE self, VALUE vplaceholder, VALUE vbindobj)
{
oci8_stmt_t *stmt = TO_STMT(self);
@@ -185,6 +212,14 @@
return rv;
}
+/*
+ * call-seq:
+ * __execute(iteration_count)
+ *
+ * @param [Integer] iteration_count
+ *
+ * @private
+ */
static VALUE oci8_stmt_execute(VALUE self, VALUE iteration_count)
{
oci8_stmt_t *stmt = TO_STMT(self);
@@ -196,6 +231,15 @@
return self;
}
+/*
+ * call-seq:
+ * __fetch(connection)
+ *
+ * @param [OCI8] connection
+ * @return [true or false] true on success and false when all rows are fetched.
+ *
+ * @private
+ */
static VALUE oci8_stmt_fetch(VALUE self, VALUE svc)
{
oci8_stmt_t *stmt = TO_STMT(self);
@@ -218,12 +262,21 @@
}
rv = OCIStmtFetch_nb(svcctx, stmt->base.hp.stmt, oci8_errhp, 1, OCI_FETCH_NEXT, OCI_DEFAULT);
if (rv == OCI_NO_DATA) {
- return Qnil;
+ return Qfalse;
}
chker3(rv, &svcctx->base, stmt->base.hp.stmt);
- return self;
+ return Qtrue;
}
+/*
+ * call-seq:
+ * __paramGet(pos)
+ *
+ * @param [Fixnum] pos Column position which starts from one
+ * @return [OCI8::Metadata::Base]
+ *
+ * @private
+ */
static VALUE oci8_stmt_get_param(VALUE self, VALUE pos)
{
oci8_stmt_t *stmt = TO_STMT(self);
@@ -239,18 +292,15 @@
}
/*
- * Get the rowid of the last inserted/updated/deleted row.
+ * Get the rowid of the last inserted, updated or deleted row.
* This cannot be used for select statements.
*
- * example:
+ * @example
* cursor = conn.parse('INSERT INTO foo_table values(:1, :2)', 1, 2)
* cursor.exec
- * cursor.rowid # => the inserted row's rowid
+ * cursor.rowid # => "AAAFlLAAEAAAAG9AAA", the inserted row's rowid
*
- * <em>Changes between ruby-oci8 1.0.3 and 1.0.4.</em>
- *
- * [ruby-oci8 1.0.4 or upper] The return value is a String.
- * [ruby-oci8 1.0.3 or lower] It returns an OCIRowid object.
+ * @return [String]
*/
static VALUE oci8_stmt_get_rowid(VALUE self)
{
Modified: trunk/ruby-oci8/lib/oci8/cursor.rb
===================================================================
--- trunk/ruby-oci8/lib/oci8/cursor.rb 2012-08-11 14:22:30 UTC (rev 532)
+++ trunk/ruby-oci8/lib/oci8/cursor.rb 2012-08-12 12:04:38 UTC (rev 533)
@@ -14,14 +14,18 @@
# calling OCI8#exec or OCI8#parse.
class Cursor
- def initialize(con, sql = nil)
+ # @note Don't use this constructor. Use {OCI8#parse} instead.
+ #
+ # @param [OCI8] conn connection
+ # @param [String] sql SQL statement
+ def initialize(conn, sql = nil)
@bind_handles = {}
@define_handles = []
@column_metadata = []
@names = nil
- @con = con
+ @con = conn
@max_array_size = nil
- __initialize(con, sql)
+ __initialize(conn, sql) # Initialize the internal C structure.
end
# explicitly indicate the date type of fetched value. run this
@@ -41,7 +45,7 @@
end
@define_handles[pos - 1] = bindobj
self
- end # define
+ end
# Binds variables explicitly.
#
@@ -99,7 +103,7 @@
end
@bind_handles[key] = bindobj
self
- end # bind_param
+ end
# Executes the SQL statement assigned the cursor. The type of
# return value depends on the type of sql statement: select;
@@ -125,12 +129,12 @@
__execute(1)
row_count
end
- end # exec
+ end
# Gets fetched data as array. This is available for select
# statement only.
#
- # example:
+ # @example
# conn = OCI8.new('scott', 'tiger')
# cursor = conn.exec('SELECT * FROM emp')
# while r = cursor.fetch()
@@ -138,6 +142,8 @@
# end
# cursor.close
# conn.logoff
+ #
+ # @return [Array]
def fetch
if block_given?
while row = fetch_one_row_as_array
@@ -149,85 +155,86 @@
end
end
- # call-seq:
- # fetch_hash
+ # Gets fetched data as a Hash. The hash keys are column names.
+ # If a block is given, acts as an iterator.
#
- # get fetched data as a Hash. The hash keys are column names.
- # If a block is given, acts as an iterator.
+ # @return [Hash] the hash keys are column names and hash values are column values
def fetch_hash
- if iterator?
- while ret = fetch_one_row_as_hash()
- yield(ret)
+ if block_given?
+ while row = fetch_one_row_as_hash()
+ yield row
end
else
fetch_one_row_as_hash
end
end
- # call-seq:
- # [key]
- #
# Gets the value of the bind variable.
#
- # In case of binding explicitly, use same key with that of
- # OCI8::Cursor#bind_param. A placeholder can be bound by
- # name or position. If you bind by name, use that name. If you bind
- # by position, use the position.
+ # When bind variables are explicitly bound by {OCI8::Cursor#bind_param},
+ # the subscript +key+ must be same with the parameter +key+ passed to {OCI8::Cursor#bind_param}.
#
- # example:
+ # When they are implicitly bound by {OCI8#exec} or {OCI8::Cursor#exec},
+ # the subscript +key+ is the position which starts from one.
+ #
+ # @example explicitly bind by name
# cursor = conn.parse("BEGIN :out := 'BAR'; END;")
- # cursor.bind_param(':out', 'FOO') # bind by name
- # p cursor[':out'] # => 'FOO'
- # p cursor[1] # => nil
+ # cursor.bind_param(:out, 'FOO') # bind by name
+ # p cursor[:out] # => 'FOO' - The subscript must be :out.
# cursor.exec()
- # p cursor[':out'] # => 'BAR'
- # p cursor[1] # => nil
+ # p cursor[:out] # => 'BAR'
#
- # example:
+ # @example explicitly bind by position
# cursor = conn.parse("BEGIN :out := 'BAR'; END;")
# cursor.bind_param(1, 'FOO') # bind by position
- # p cursor[':out'] # => nil
- # p cursor[1] # => 'FOO'
+ # p cursor[1] # => 'FOO' - The subscript must be 1.
# cursor.exec()
- # p cursor[':out'] # => nil
# p cursor[1] # => 'BAR'
#
- # In case of binding by OCI8#exec or OCI8::Cursor#exec,
- # get the value by position, which starts from 1.
- #
- # example:
+ # @example implicitly bind
# cursor = conn.exec("BEGIN :out := 'BAR'; END;", 'FOO')
# # 1st bind variable is bound as String with width 3. Its initial value is 'FOO'
# # After execute, the value become 'BAR'.
# p cursor[1] # => 'BAR'
+ #
+ # @param [Object] key bind key
+ # @return [Object] the value of the bind variable
+ #
def [](key)
handle = @bind_handles[key]
handle && handle.send(:get_data)
end
- # call-seq:
- # [key] = val
+ # Changes the bind variable value.
#
- # Sets the value to the bind variable. The way to specify the
- # +key+ is same with OCI8::Cursor#[]. This is available
- # to replace the value and execute many times.
+ # When bind variables are explicitly bound by {OCI8::Cursor#bind_param},
+ # the subscript +key+ must be same with the parameter +key+ passed to {OCI8::Cursor#bind_param}.
#
- # example1:
+ # When they are implicitly bound by {OCI8#exec} or {OCI8::Cursor#exec},
+ # the subscript +key+ is the position which starts from one.
+ #
+ # @example
+ # # Inserts three rows whose values are 'FOO', 'BAR' and 'BAZ.'
# cursor = conn.parse("INSERT INTO test(col1) VALUES(:1)")
- # cursor.bind_params(1, nil, String, 3)
- # ['FOO', 'BAR', 'BAZ'].each do |key|
- # cursor[1] = key
- # cursor.exec
+ # begin
+ # cursor.bind_params(1, nil, String, 3)
+ # ['FOO', 'BAR', 'BAZ'].each do |column_value|
+ # cursor[1] = column_value # Change the bind value
+ # cursor.exec # and insert it.
+ # end
+ # ensure
+ # cursor.close()
# end
- # cursor.close()
+ # # This makes same result with the following but is more efficient.
+ # #
+ # # ['FOO', 'BAR', 'BAZ'].each do |column_value|
+ # # conn.exec("INSERT INTO test(col1) VALUES(:1)", column_value)
+ # # end
+ # #
#
- # example2:
- # ['FOO', 'BAR', 'BAZ'].each do |key|
- # conn.exec("INSERT INTO test(col1) VALUES(:1)", key)
- # end
+ # @param [Object] key bind key
+ # @param [Object] val bind value
#
- # Both example's results are same. But the former will use less resources.
- #
def []=(key, val)
handle = @bind_handles[key]
return nil if handle.nil?
@@ -255,16 +262,16 @@
free_bind_handles() if !@max_array_size.nil?
@max_array_size = size
@actual_array_size = nil
- end # max_array_size=
+ end
- # Bind array explicitly
+ # Binds array explicitly
#
# When key is number, it binds by position, which starts from 1.
# When key is string, it binds by the name of placeholder.
#
# The max_array_size should be set before calling bind_param_array
#
- # example:
+ # @example
# cursor = conn.parse("INSERT INTO test_table VALUES (:str)")
# cursor.max_array_size = 3
# cursor.bind_param_array(1, ['happy', 'new', 'year'], String, 30)
@@ -307,7 +314,7 @@
end
@bind_handles[key] = bindobj
self
- end # bind_param_array
+ end
# Executes the SQL statement assigned the cursor with array binding
def exec_array
@@ -325,22 +332,17 @@
else
true
end
- end # exec_array
+ end
# Gets the names of select-list as array. Please use this
# method after exec.
def get_col_names
@names ||= @column_metadata.collect { |md| md.name }
- end # get_col_names
+ end
- # call-seq:
- # column_metadata -> column information
- #
- # (new in 1.0.0 and 2.0)
- #
# Gets an array of OCI8::Metadata::Column of a select statement.
#
- # example:
+ # @example
# cursor = conn.exec('select * from tab')
# puts ' Name Type'
# puts ' ----------------------------------------- ----------------------------'
@@ -349,6 +351,10 @@
# colinfo.name,
# colinfo.type_string)
# end
+ #
+ # @return [Array of OCI8::Metadata::Column]
+ #
+ # @since 1.0.0
def column_metadata
@column_metadata
end
@@ -358,30 +364,29 @@
free()
@names = nil
@column_metadata = nil
- end # close
+ end
- # call-seq:
- # keys -> an Array
+ # Returns the keys of bind variables.
#
- # Returns the keys of bind variables as array.
+ # @return [Array] bind variable keys
def keys
@bind_handles.keys
end
- # call-seq:
- # prefetch_rows = aFixnum
- #
- # Set number of rows to be prefetched.
+ # Set the number of rows to be prefetched.
# This can reduce the number of network round trips when fetching
# many rows. The default value is one.
#
# FYI: Rails oracle adaptor uses 100 by default.
#
+ # @param [Fixnum] rows The number of rows to be prefetched
def prefetch_rows=(rows)
attr_set_ub4(11, rows) # OCI_ATTR_PREFETCH_ROWS(11)
end
# Returns the number of processed rows.
+ #
+ # @return [Integer]
def row_count
# http://docs.oracle.com/cd/E11882_01/appdev.112/e10646/ociaahan.htm#sthref5498
attr_get_ub4(9) # OCI_ATTR_ROW_COUNT(9)
@@ -398,7 +403,10 @@
# cursor = conn.parse("select * from country where country_code = 'ja'")
# cursor.statement # => "select * from country where country_code = 'ja'"
#
- # @return [String]
+ # @return [String] prepared SQL statement
+ #
+ # @since 2.1.3
+ #
def statement
# The magic number 144 is OCI_ATTR_STATEMENT.
# See http://docs.oracle.com/cd/E11882_01/appdev.112/e10646/ociaahan.htm#sthref5503
@@ -503,7 +511,7 @@
@column_metadata[i - 1] = parm
end
num_cols
- end # define_columns
+ end
def define_one_column(pos, param)
bindobj = make_bind_object(param)
@@ -512,7 +520,7 @@
old.send(:free)
end
@define_handles[pos - 1] = bindobj
- end # define_one_column
+ end
def bind_params(*bindvars)
bindvars.each_with_index do |val, i|
@@ -522,7 +530,7 @@
bind_param(i + 1, val)
end
end
- end # bind_params
+ end
def fetch_one_row_as_array
if __fetch(@con)
More information about the ruby-oci8-commit
mailing list