[ruby-oci8-commit] [502] trunk/ruby-oci8: revise rdoc comments.
nobody at rubyforge.org
nobody at rubyforge.org
Sun Apr 8 11:32:56 UTC 2012
Revision: 502
Author: kubo
Date: 2012-04-08 11:32:55 +0000 (Sun, 08 Apr 2012)
Log Message:
-----------
revise rdoc comments.
Modified Paths:
--------------
trunk/ruby-oci8/ChangeLog
trunk/ruby-oci8/ext/oci8/lob.c
trunk/ruby-oci8/ext/oci8/win32.c
trunk/ruby-oci8/lib/oci8/oracle_version.rb
Modified: trunk/ruby-oci8/ChangeLog
===================================================================
--- trunk/ruby-oci8/ChangeLog 2012-04-06 12:26:57 UTC (rev 501)
+++ trunk/ruby-oci8/ChangeLog 2012-04-08 11:32:55 UTC (rev 502)
@@ -1,3 +1,7 @@
+2012-04-08 KUBO Takehiro <kubo at jiubao.org>
+ * ext/oci8/lob.c, ext/oci8/win32.c, lib/oci8/oracle_version.rb:
+ revise rdoc comments.
+
2012-04-06 KUBO Takehiro <kubo at jiubao.org>
* ext/oci8/error.c, ext/oci8/ocihandle.c, ext/oci8/oradate.c,
lib/oci8/encoding-init.rb, lib/oci8/oci8.rb, lib/oci8/ocihandle.rb:
Modified: trunk/ruby-oci8/ext/oci8/lob.c
===================================================================
--- trunk/ruby-oci8/ext/oci8/lob.c 2012-04-06 12:26:57 UTC (rev 501)
+++ trunk/ruby-oci8/ext/oci8/lob.c 2012-04-08 11:32:55 UTC (rev 502)
@@ -163,6 +163,41 @@
}
}
+/*
+ * Document-class: OCI8::LOB
+ *
+ * This is the abstract base class of large-object data types; BFILE, BLOB, CLOB and NCLOB.
+ *
+ */
+
+/*
+ * Document-class: OCI8::CLOB
+ *
+ */
+
+/*
+ * Document-class: OCI8::NCLOB
+ *
+ */
+
+/*
+ * Document-class: OCI8::BLOB
+ *
+ */
+
+/*
+ * Document-class: OCI8::BFILE
+ *
+ * @method truncate(length)
+ * @method size = length
+ * @method write(data)
+ */
+
+/*
+ * Closes the lob.
+ *
+ * @return [self]
+ */
static VALUE oci8_lob_close(VALUE self)
{
oci8_lob_t *lob = DATA_PTR(self);
@@ -203,24 +238,82 @@
return Qnil;
}
+/*
+ * call-seq:
+ * initialize(conn, contents = nil)
+ *
+ * Creates a temporary CLOB when <i>contents</i> is not nil.
+ * Otherwise, it creates an uninitialized lob, which is used internally
+ * to fetch CLOB column data.
+ *
+ * @example
+ * # Inserts a file name and its contents as CLOB.
+ * clob = OCI8::CLOB.new(conn, File.read(file_name))
+ * conn.exec('insert into file_contents values (:1, :2)', file_name, clob)
+ *
+ * @param [OCI8] conn connection
+ * @param [String] contents
+ * @return [OCI8::CLOB]
+ */
static VALUE oci8_clob_initialize(int argc, VALUE *argv, VALUE self)
{
oci8_lob_do_initialize(argc, argv, self, SQLCS_IMPLICIT, OCI_TEMP_CLOB);
return Qnil;
}
+/*
+ * call-seq:
+ * initialize(conn, contents = nil)
+ *
+ * Creates a temporary NCLOB when <i>contents</i> is not nil.
+ * Otherwise, it creates an uninitialized lob, which is used internally
+ * to fetch NCLOB column data.
+ *
+ * @example
+ * # Inserts a file name and its contents as NCLOB.
+ * clob = OCI8::NCLOB.new(conn, File.read(file_name))
+ * conn.exec('insert into file_contents values (:1, :2)', file_name, clob)
+ *
+ * @param [OCI8] conn
+ * @param [String] contents
+ * @return [OCI8::NCLOB]
+ */
static VALUE oci8_nclob_initialize(int argc, VALUE *argv, VALUE self)
{
oci8_lob_do_initialize(argc, argv, self, SQLCS_NCHAR, OCI_TEMP_CLOB);
return Qnil;
}
+/*
+ * call-seq:
+ * initialize(conn, contents = nil)
+ *
+ * Creates a temporary BLOB when <i>contents</i> is not nil.
+ * Otherwise, it creates an uninitialized lob, which is used internally
+ * to fetch BLOB column data.
+ *
+ * @example
+ * # Inserts a file name and its contents as BLOB.
+ * clob = OCI8::BLOB.new(conn, File.read(file_name, :mode => 'rb'))
+ * conn.exec('insert into file_contents values (:1, :2)', file_name, clob)
+ *
+ * @param [OCI8] conn
+ * @param [String] contents
+ * @return [OCI8::BLOB]
+ */
static VALUE oci8_blob_initialize(int argc, VALUE *argv, VALUE self)
{
oci8_lob_do_initialize(argc, argv, self, SQLCS_IMPLICIT, OCI_TEMP_BLOB);
return Qnil;
}
+/*
+ * call-seq:
+ * __char_width = size
+ *
+ * @private
+ * IMO, nobody need and use this.
+ */
static VALUE oci8_lob_set_char_width(VALUE self, VALUE vsize)
{
oci8_lob_t *lob = DATA_PTR(self);
@@ -234,6 +327,11 @@
return vsize;
}
+/*
+ * Returns +true+ when <i>self</i> is initialized.
+ *
+ * @return [true or false]
+ */
static VALUE oci8_lob_available_p(VALUE self)
{
oci8_lob_t *lob = DATA_PTR(self);
@@ -244,17 +342,36 @@
return is_initialized ? Qtrue : Qfalse;
}
+/*
+ * Returns the size.
+ * For CLOB and NCLOB it is the number of characters,
+ * for BLOB and BFILE it is the number of bytes.
+ *
+ * @return [Integer]
+ */
static VALUE oci8_lob_get_size(VALUE self)
{
return UB4_TO_NUM(oci8_lob_get_length(DATA_PTR(self)));
}
+/*
+ * Returns the current offset.
+ * For CLOB and NCLOB it is the number of characters,
+ * for BLOB and BFILE it is the number of bytes.
+ *
+ * @return [Integer]
+ */
static VALUE oci8_lob_get_pos(VALUE self)
{
oci8_lob_t *lob = DATA_PTR(self);
return UB4_TO_NUM(lob->pos);
}
+/*
+ * Returns true if the current offset is at end of lob.
+ *
+ * @return [true or false]
+ */
static VALUE oci8_lob_eof_p(VALUE self)
{
oci8_lob_t *lob = DATA_PTR(self);
@@ -264,6 +381,20 @@
return Qtrue;
}
+/*
+ * call-seq:
+ * seek(amount, whence=IO::SEEK_SET)
+ *
+ * Seeks to the given offset in the stream. The new position, measured in characters,
+ * is obtained by adding offset <i>amount</i> to the position specified by <i>whence</i>.
+ * If <i>whence</i> is set to IO::SEEK_SET, IO::SEEK_CUR, or IO::SEEK_END,
+ * the offset is relative to the start of the file, the current position
+ * indicator, or end-of-file, respectively.
+ *
+ * @param [Integer] amount
+ * @param [IO::SEEK_SET, IO::SEEK_CUR or IO::SEEK_END] whence
+ * @return [self]
+ */
static VALUE oci8_lob_seek(int argc, VALUE *argv, VALUE self)
{
oci8_lob_t *lob = DATA_PTR(self);
@@ -288,6 +419,11 @@
return self;
}
+/*
+ * Sets the current offset at the beginning.
+ *
+ * @return [true or false]
+ */
static VALUE oci8_lob_rewind(VALUE self)
{
oci8_lob_t *lob = DATA_PTR(self);
@@ -295,6 +431,15 @@
return self;
}
+/*
+ * call-seq:
+ * truncate(length)
+ *
+ * Changes the lob size to the given <i>length</i>.
+ *
+ * @param [Integer] length
+ * @return [self]
+ */
static VALUE oci8_lob_truncate(VALUE self, VALUE len)
{
oci8_lob_t *lob = DATA_PTR(self);
@@ -306,12 +451,32 @@
return self;
}
+/*
+ * call-seq:
+ * size = length
+ *
+ * Changes the lob size to the given <i>length</i>.
+ *
+ * @param [Integer] length
+ * @return [Integer]
+ */
static VALUE oci8_lob_set_size(VALUE self, VALUE len)
{
oci8_lob_truncate(self, len);
return len;
}
+/*
+ * call-seq:
+ * read(length = nil)
+ *
+ * Reads <i>length</i> characters for CLOB and NCLOB or <i>length</i>
+ * bytes for BLOB and BILF from the current position.
+ * When <i>length</i> is nil, it reads data until EOF.
+ *
+ * @param [Integer] length
+ * @return [String]
+ */
static VALUE oci8_lob_read(int argc, VALUE *argv, VALUE self)
{
oci8_lob_t *lob = DATA_PTR(self);
@@ -412,6 +577,15 @@
}
}
+/*
+ * call-seq:
+ * write(data)
+ *
+ * Writes <i>data</i>.
+ *
+ * @param [String] data
+ * @return [Integer]
+ */
static VALUE oci8_lob_write(VALUE self, VALUE data)
{
oci8_lob_t *lob = DATA_PTR(self);
@@ -433,12 +607,20 @@
return UINT2NUM(amt);
}
+/*
+ * @deprecated I'm not sure that this is what the name indicates.
+ * @private
+ */
static VALUE oci8_lob_get_sync(VALUE self)
{
oci8_lob_t *lob = DATA_PTR(self);
return (lob->state == S_NO_OPEN_CLOSE) ? Qtrue : Qfalse;
}
+/*
+ * @deprecated I'm not sure that this is what the name indicates.
+ * @private
+ */
static VALUE oci8_lob_set_sync(VALUE self, VALUE b)
{
oci8_lob_t *lob = DATA_PTR(self);
@@ -452,6 +634,10 @@
return b;
}
+/*
+ * @deprecated I'm not sure that this is what the name indicates.
+ * @private
+ */
static VALUE oci8_lob_flush(VALUE self)
{
oci8_lob_t *lob = DATA_PTR(self);
@@ -459,6 +645,12 @@
return self;
}
+/*
+ * Returns the chunk size of a LOB.
+ *
+ * @see http://docs.oracle.com/cd/E16338_01/appdev.112/e10646/oci17msc002.htm#i493090
+ * @return [Integer]
+ */
static VALUE oci8_lob_get_chunk_size(VALUE self)
{
oci8_lob_t *lob = DATA_PTR(self);
@@ -544,6 +736,19 @@
&lob->base);
}
+/*
+ * call-seq:
+ * initialize(conn, dir_alias = nil, filename = nil)
+ *
+ * Creates a BFILE object.
+ * This is correspond to {http://docs.oracle.com/cd/E11882_01/server.112/e17118/functions019.htm#sthref953 BFILENAME}.
+ *
+ * @param [OCI8] conn
+ * @param [String] dir_alias a directory object created by
+ * {http://docs.oracle.com/cd/E11882_01/server.112/e17118/statements_5007.htm "CREATE DIRECTORY"}.
+ * @param [String] filename
+ * @return [OCI8::BFILE]
+ */
static VALUE oci8_bfile_initialize(int argc, VALUE *argv, VALUE self)
{
oci8_lob_t *lob = DATA_PTR(self);
@@ -574,6 +779,11 @@
return Qnil;
}
+/*
+ * Returns the directory object name.
+ *
+ * @return [String]
+ */
static VALUE oci8_bfile_get_dir_alias(VALUE self)
{
VALUE dir_alias;
@@ -582,6 +792,11 @@
return dir_alias;
}
+/*
+ * Returns the file name.
+ *
+ * @return [String]
+ */
static VALUE oci8_bfile_get_filename(VALUE self)
{
VALUE filename;
@@ -590,6 +805,14 @@
return filename;
}
+/*
+ * call-seq:
+ * dir_alias = name
+ *
+ * Changes the directory object name.
+ *
+ * @param [String] name
+ */
static VALUE oci8_bfile_set_dir_alias(VALUE self, VALUE dir_alias)
{
VALUE filename;
@@ -601,6 +824,14 @@
return dir_alias;
}
+/*
+ * call-seq:
+ * filename = name
+ *
+ * Changes the file name.
+ *
+ * @param [String] name
+ */
static VALUE oci8_bfile_set_filename(VALUE self, VALUE filename)
{
VALUE dir_alias;
@@ -612,6 +843,11 @@
return filename;
}
+/*
+ * Returns <code>true</code> when the BFILE exists on the server's operating system.
+ *
+ * @return [true or false]
+ */
static VALUE oci8_bfile_exists_p(VALUE self)
{
oci8_lob_t *lob = DATA_PTR(self);
@@ -623,6 +859,39 @@
return flag ? Qtrue : Qfalse;
}
+/*
+ * Document-method: OCI8::BFILE#truncate
+ *
+ * call-seq:
+ * truncate(length)
+ *
+ * Raises <code>RuntimeError</code>.
+ *
+ * @raise [RuntimeError] cannot modify a read-only BFILE object
+ */
+
+/*
+ * Document-method: OCI8::BFILE#size=
+ *
+ * call-seq:
+ * size = length
+ *
+ * Raises <code>RuntimeError</code>.
+ *
+ * @raise [RuntimeError] cannot modify a read-only BFILE object
+ */
+
+/*
+ * Document-method: OCI8::BFILE#write
+ *
+ * call-seq:
+ * write(data)
+ *
+ * Raises <code>RuntimeError</code>.
+ *
+ * @raise [RuntimeError] cannot modify a read-only BFILE object
+ */
+
static VALUE oci8_bfile_error(VALUE self, VALUE dummy)
{
rb_raise(rb_eRuntimeError, "cannot modify a read-only BFILE object");
@@ -761,6 +1030,12 @@
seek_cur = rb_eval_string("::IO::SEEK_CUR");
seek_end = rb_eval_string("::IO::SEEK_END");
+#if 0
+ cOCIHandle = rb_define_class("OCIHandle", rb_cObject);
+ cOCI8 = rb_define_class("OCI8", cOCIHandle);
+ cOCI8LOB = rb_define_class_under(cOCI8, "LOB", cOCIHandle);
+#endif
+
cOCI8LOB = oci8_define_class_under(cOCI8, "LOB", &oci8_lob_vtable);
cOCI8CLOB = rb_define_class_under(cOCI8, "CLOB", cOCI8LOB);
cOCI8NCLOB = rb_define_class_under(cOCI8, "NCLOB", cOCI8LOB);
Modified: trunk/ruby-oci8/ext/oci8/win32.c
===================================================================
--- trunk/ruby-oci8/ext/oci8/win32.c 2012-04-06 12:26:57 UTC (rev 501)
+++ trunk/ruby-oci8/ext/oci8/win32.c 2012-04-08 11:32:55 UTC (rev 502)
@@ -13,6 +13,14 @@
#endif
#include <windows.h>
+/*
+ * Document-module: OCI8::Win32Util
+ *
+ * Windows specific utility module.
+ *
+ * @private
+ */
+
NORETURN(static void raise_error(void));
static void raise_error(void)
@@ -33,6 +41,11 @@
rb_raise(rb_eRuntimeError, "%s", msg);
}
+/*
+ * Returns the full path of OCI.DLL used by the current process.
+ *
+ * @return [String]
+ */
static VALUE dll_path(VALUE module)
{
HMODULE hModule;
@@ -120,6 +133,15 @@
return Qnil;
}
+/*
+ * Enumerates full clients' Oracle homes and NLS_LANG parameters
+ * registerd in the Windows registry.
+ *
+ * @yield [oracle_home, nls_lang]
+ * @yieldparam [String] oracle_home
+ * @yieldparam [String] nls_lang
+ * @return [nil]
+ */
static VALUE enum_homes(VALUE module)
{
enum_homes_arg_t arg;
Modified: trunk/ruby-oci8/lib/oci8/oracle_version.rb
===================================================================
--- trunk/ruby-oci8/lib/oci8/oracle_version.rb 2012-04-06 12:26:57 UTC (rev 501)
+++ trunk/ruby-oci8/lib/oci8/oracle_version.rb 2012-04-08 11:32:55 UTC (rev 502)
@@ -2,14 +2,16 @@
#
# Copyright (C) 2009 KUBO Takehiro <kubo at jiubao.org>
-#--
-
+#
class OCI8
- # A data class, representing Oracle version.
+ # The data class, representing Oracle version.
#
# Oracle version is represented by five numbers:
# *major*, *minor*, *update*, *patch* and *port_update*.
+ #
+ # @see OCI8.oracle_client_version
+ # @see OCI8#oracle_server_version
class OracleVersion
include Comparable
@@ -24,7 +26,7 @@
# The fourth part of the Oracle version.
attr_reader :port_update
- # Creates a OCI8::OracleVersion object.
+ # Creates an OCI8::OracleVersion object.
#
# If the first argument _arg_ is a String, it is parsed as dotted
# version string. If it is bigger than 0x08000000, it is parsed as
@@ -33,20 +35,32 @@
# patch and port_update. Unspecified version numbers are zeros by
# default.
#
- # == Example
- # oraver = OCI8::OracleVersion.new('10.2.0.4')
- # oraver.major # => 10
+ # @example
+ # # When the first argument is a String,
+ # oraver = OCI8::OracleVersion.new('11.2.0.3')
+ # oraver.major # => 11
# oraver.minor # => 2
# oraver.update # => 0
- # oraver.patch # => 4
+ # oraver.patch # => 3
# oraver.port_update # => 0
#
- # oraver = OCI8::OracleVersion.new(0x0a200400)
- # oraver.major # => 10
+ # # When the first argument is bigger than 0x08000000,
+ # oraver = OCI8::OracleVersion.new(0x0b200300)
+ # oraver.major # => 11
# oraver.minor # => 2
# oraver.update # => 0
- # oraver.patch # => 4
+ # oraver.patch # => 3
# oraver.port_update # => 0
+ #
+ # # Otherwise,
+ # oraver = OCI8::OracleVersion.new(11, 2, 0, 3)
+ # oraver.major # => 11
+ # oraver.minor # => 2
+ # oraver.update # => 0
+ # oraver.patch # => 3
+ # oraver.port_update # => 0
+ #
+ # @return [OCI8::OracleVersion]
def initialize(arg, minor = nil, update = nil, patch = nil, port_update = nil)
if arg.is_a? String
major, minor, update, patch, port_update = arg.split('.').collect do |v|
@@ -68,13 +82,12 @@
@port_update = port_update || 0
end
- # :call-seq:
- # oraver <=> other_oraver -> -1, 0, +1
+ # Compares +self+ and +other+.
#
- # Compares +oraver+ and +other_oraver+.
+ # <=> is the basis for the methods <, <=, ==, >, >=, and between?,
+ # included from the Comparable module.
#
- # <=> is the basis for the methods <, <=, ==, >, >=, and between?,
- # included from module Comparable.
+ # @return [-1, 0, +1]
def <=>(other)
cmp = @major <=> other.major
return cmp if cmp != 0
@@ -87,57 +100,50 @@
@port_update <=> other.port_update
end
- # :call-seq:
- # oraver.to_i -> integer
- #
# Returns an integer number contains 5-digit Oracle version.
#
# If the hexadecimal notation is 0xAABCCDEE, *major*, *minor*,
# *update*, *patch* and *port_update* are 0xAA, 0xB, 0xCC, 0xD and
# 0xEE respectively.
#
- # == Example
- # oraver = OCI8::OracleVersion.new('10.2.0.4')
- # oraver.to_i # => 169870336
- # '%08x' % oraver.to_i # => "0a200400"
+ # @example
+ # oraver = OCI8::OracleVersion.new('11.2.0.3')
+ # oraver.to_i # => 186647296
+ # '%08x' % oraver.to_i # => "0b200300"
+ #
+ # @return [Integer]
def to_i
(@major << 24) | (@minor << 20) | (@update << 12) | (@patch << 8) | @port_update
end
- # :call-seq:
- # oraver.to_s -> string
- #
# Returns a dotted version string of the Oracle version.
#
- # == Example
- # oraver = OCI8::OracleVersion.new('10.2.0.4')
- # oraver.to_s # => '10.2.0.4.0'
+ # @example
+ # oraver = OCI8::OracleVersion.new('11.2.0.3')
+ # oraver.to_s # => '11.2.0.3.0'
+ #
+ # @return [Integer]
def to_s
format('%d.%d.%d.%d.%d', @major, @minor, @update, @patch, @port_update)
end
- # :call-seq:
- # oraver.eql? other -> true or false
+ # Returns true if +self+ and +other+ are the same type and have
+ # equal values.
#
- # Returns true if +oraver+ and +other+ are the same type and have
- # equal values.
- #--
- # This is for class Hash to test members for equality.
+ # @return [true or false]
def eql?(other)
other.is_a? OCI8::OracleVersion and (self <=> other) == 0
end
- # :call-seq:
- # oraver.hash -> integer
+ # Returns a hash based on the value of +self+.
#
- # Returns a hash based on the value of +oraver+.
- #--
- # This is for class Hash.
+ # @return [Integer]
def hash
to_i
end
- def inspect # :nodoc:
+ # @private
+ def inspect
"#<#{self.class.to_s}: #{self.to_s}>"
end
end
More information about the ruby-oci8-commit
mailing list