From nobody at rubyforge.org  Mon Apr  2 13:47:35 2012
From: nobody at rubyforge.org (nobody at rubyforge.org)
Date: Mon,  2 Apr 2012 13:47:35 +0000 (UTC)
Subject: [ruby-oci8-commit] [498] trunk/ruby-oci8: change the text format to
	markdown.
Message-ID: <20120402134735.3B6DC4A80F@rubyforge.org>

Revision: 498
Author:   kubo
Date:     2012-04-02 13:47:34 +0000 (Mon, 02 Apr 2012)
Log Message:
-----------
change the text format to markdown.

Modified Paths:
--------------
    trunk/ruby-oci8/ChangeLog
    trunk/ruby-oci8/NEWS

Modified: trunk/ruby-oci8/ChangeLog
===================================================================
--- trunk/ruby-oci8/ChangeLog	2012-03-18 14:05:22 UTC (rev 497)
+++ trunk/ruby-oci8/ChangeLog	2012-04-02 13:47:34 UTC (rev 498)
@@ -1,3 +1,6 @@
+2012-04-02  KUBO Takehiro  <kubo at jiubao.org>
+	* NEWS: change the text format to markdown.
+
 2012-03-18  KUBO Takehiro  <kubo at jiubao.org>
 	* test/test_datetime.rb: fix testcase failures in DST.
 	    (reported by Yasuo Honda)

Modified: trunk/ruby-oci8/NEWS
===================================================================
--- trunk/ruby-oci8/NEWS	2012-03-18 14:05:22 UTC (rev 497)
+++ trunk/ruby-oci8/NEWS	2012-04-02 13:47:34 UTC (rev 498)
@@ -1,414 +1,470 @@
-2.1.0:
+# @markup markdown
 
-*** Ruby-oci8 2.1.0 doesn't support Oracle 8 (8.0) and Oracle 8i (8.1) anymore. ***
+2.1.0
+=====
 
-* New Features
+New Features
+------------
 
-  - OCI connection pooling
+### OCI connection pooling
 
-    See: http://docs.oracle.com/cd/E11882_01/appdev.112/e10646/oci09adv.htm#sthref1479
-    and http://docs.oracle.com/cd/E11882_01/java.112/e16548/ociconpl.htm#JJDBC28789
+See: {OCI8::ConnectionPool}
 
-    Example:
+### Daylight saving time aware if TZ is set.
 
-      # Create a connection pool.
-      # username and password are required to establish an implicit primary session.
-      cpool = OCI8::ConnectionPool.new(1, 5, 2, username, password, database)
+You should set the environment variable TZ if your applications run
+in a time zone with daylight saving time transitions.
+Otherwise, Oracle session time zone is set with current constant
+offset from GMT.
+(reported by Yasuo Honda)
 
-      # Get a session from the pool.
-      # Pass the connection pool to the third argument.
-      conn1 = OCI8.new(username, password, cpool)
+### connect as sysasm (Oracle 11g only)
 
-      # Get another session.
-      conn2 = OCI8.new(username, password, cpool)
+You can connect to the Oracle server as SYSASM privilege as follows:
 
-  - Daylight saving time aware if TZ is set.
+    OCI8.new('username/password as sysasm')
 
-    You should set the environment variable TZ if your applications run
-    in a time zone with daylight saving time transitions.
-    Otherwise, Oracle session time zone is set with current constant
-    offset from GMT.
-    (reported by Yasuo Honda)
+or
 
-  - connect as sysasm (Oracle 11g only)
+    OCI8.new('username', 'password', nil, :SYSASM)
 
-      OCI8.new('username/password as sysasm')
-    or
-      OCI8.new('username', 'password', nil, :SYSASM)
+### Oracle number is converted to ruby float exactly same as ruby does.
 
-  - Oracle number is converted to ruby float exactly same as ruby does.
+From ruby 1.9.2, a float value converted from Oracle number 15.7 by
+the Oracle function OCINumberToReal() makes a string representation
+15.700000000000001 by `Float#to_s`. (See: {http://redmine.ruby-lang.org/issues/4656})
+To avoid this issue, any Oracle number is converted to a float as
+ruby's `String#to_f` does.
 
-    From ruby 1.9.2, a float value converted from Oracle number 15.7 by
-    the Oracle function OCINumberToReal() makes a string representation
-    15.700000000000001 by Float#to_s. (See: http://redmine.ruby-lang.org/issues/4656)
-    To avoid this issue, any Oracle number is converted to a float as
-    ruby's String#to_f does.
+The behavior is customizable by {OCI8.properties OCI8.properties[:float\_conversion\_type]}.
 
-    The behavior is customizable by OCI8.properties[:float_conversion_type].
+    OCI8.properties[:float_conversion_type] = :oracle # => Use OCINumberToReal()
+    OCI8.properties[:float_conversion_type] = :ruby # => Use String#to_f
 
-      OCI8.properties[:float_conversion_type] = :oracle # => Use OCINumberToReal()
-      OCI8.properties[:float_conversion_type] = :ruby # => Use String#to_f
+The default value is :ruby.
 
-    The default value is :ruby.
+### `OCISuccessWithInfo` exceptions are not raised any more.
 
-  - OCI_SUCCESS_WITH_INFO handling is changed.
+Ruby-oci8 2.0 treats `OCI_SUCCESS_WITH_INFO` in OCI layer as an error
+and raise an exception {OCISuccessWithInfo} such as "ORA-24347: Warning of
+a NULL column in an aggregate function" and "ORA-28002: the password will
+expire within xx days."
 
-    Ruby-oci8 2.0 treats OCI_SUCCESS_WITH_INFO in OCI layer as an error
-    and raise an exception OCISuccessWithInfo such as "ORA-24347: Warning of
-    a NULL column in an aggregate function" and "ORA-28002: the password will
-    expire within xx days."
+From 2.1.0, it is treated as a warning and the exception is set
+to {OCI8#last_error}.
 
-    From 2.1.0, it is treated as a warning and the exception is set
-    to OCI8#last_error.
+### {OCI8#last_error} is added.
 
-  - OCI8#last_error
+The last error or warning associated with the session is set to
+{OCI8#last_error}. The usecase is to detect {OCISuccessWithInfo}.
+It is reset by {OCI8#exec} and {OCI8#parse}.
 
-    The last error or warning associated with the session is set to
-    OCI8#last_error. The usecase is to detect OCI_SUCCESS_WITH_INFO.
-    It is reset by OCI8#exec and OCI8#parse.
+### Experimental support of character length semantics
 
-  - Experimental support of character length semantics
+{OCI8.properties OCI8.properties[:length\_semantics]} indicates length semantics
+of {OCI8::Cursor#bind\_param}. When it is `:char`, the length is counted by the
+number of characters. When it is `:byte`, it is counted by the number of
+bytes.
 
-    This is enabled when :char is set to OCI8.properties[:length_semantics].
+### {OCI8.client\_charset\_name} and {OCI8#database\_charset\_name} are added.
 
-  - OCI8.client_charset_name and OCI8#database_charset_name is added.
+They return Oracle charset name such as WE8ISO8859P15.
 
-    They return Oracle charset name such as WE8ISO8859P15.
+Specification changes
+---------------------
 
-* Specification changes
+### The parent class {OCINoData} was changed from {OCIException} to {OCIError}.
 
-  - The parent class OCINoData was changed from OCIException to OCIError.
+### Oracle 8 and Oracie 8i is not supported anymore.
 
-* Fixed Issues
+Fixed Issues
+------------
 
-  - Fix a bug that an array is always bound as null.
+-   Fix a bug that an array is always bound as null.
     This bug was introduced in ruby-oci8 2.0.5.
+
     (reported by Leo? Bitto)
 
-  - Avoid a gcc internal compiler error when using ruby1.9.2-p290 on
-    ubuntu 11.10 (64bit). (reported by Bob Saveland.)
+-   Avoid a gcc internal compiler error when using ruby1.9.2-p290 on
+    ubuntu 11.10 (64bit).
 
-  - Fix compilation problems on Solaris.
+    (reported by Bob Saveland.)
+
+-   Fix compilation problems on Solaris.
+
     (Reported by Sanjiv Patel.)
 
-  - Fix compilation problems on Linux.
+-   Fix compilation problems on Linux.
+
     (Reported by Edgars Beigarts.)
 
-  - Connections are released by GC without explicit logoff.
+-   Connections are released by GC without explicit logoff.
 
-  - Set ruby encoding CP950 for oracle characterset ZHT16MSWIN950 and
+-   Set ruby encoding CP950 for oracle characterset ZHT16MSWIN950 and
     CP951 for ZHT16HKSCS and ZHT16HKSCS31 when the ruby is 1.9.3.
 
-  - Clear an executuing thread information in a connection when a SQL
+-   Clear an executuing thread information in a connection when a SQL
     executions is canceled by Thread#kill or Timeout::timeout.
+
     (reported by Aaron Qian)
 
-  - Fix some test cases for object type and TZ issues.
+-   Fix some test cases for object type and TZ issues.
+
     (reported by Yasuo Honda)
 
-  - Use Gem::Command.build_args to get arguments after '--'.
+-   Use Gem::Command.build_args to get arguments after '--'.
+
     (reported by jbirdjavi)
 
-2.0.6:
+2.0.6
+=====
 
-* Fixed issues
+Fixed issues
+------------
 
-  - fix SEGV when freeing a temporary LOB during GC on rubinius 1.2.3.
+-   fix SEGV when freeing a temporary LOB during GC on rubinius 1.2.3.
 
-  - revert the exception type from RuntimeError to OCIException when
+-   revert the exception type from RuntimeError to OCIException when
     a closed OCI handle's method is called. It was chaned in 2.0.5
     by mistake.
 
-2.0.5:
+2.0.5
+=====
 
-* New Features
+New Features
+------------
 
-  - Support Rubinius.
+### Support Rubinius.
 
-  - OraNumber#has_decimal_part? -> boolean
+### {OraNumber#has\_decimal\_part?} is added.
 
-      OraNumber(10).has_decimal_part?   # => false
-      OraNumber(10.1).has_decimal_part? # => true
+Example:
 
-  - Limitted support for OraNumber's positive and negative infinity.
+    OraNumber(10).has_decimal_part?   # => false
+    OraNumber(10.1).has_decimal_part? # => true
 
-    They are converted to '~' and '-~' respectively as described in
-    <URL:http://www.ixora.com.au/notes/infinity.htm>.
+### Limitted support for OraNumber's positive and negative infinity.
 
-  - OCI8.properties is added to control ruby-oci8 behaviour.
-    It supports :bind_string_as_nchar only for now.
+They are converted to '~' and '-~' respectively as described in
+{http://www.ixora.com.au/notes/infinity.htm}.
 
-  - OCI8.properties[:bind_string_as_nchar] is added.
+### {OCI8.properties} is added to control ruby-oci8 behaviour.
 
-    You need to set "OCI8.properties[:bind_string_as_nchar] = true"
-    if the database character set is not UTF-8 and NCHAR/NVARCHAR2 columns
-    contain characters which cannot be converted to the database character set.
-    See: http://rubyforge.org/forum/forum.php?thread_id=48838&forum_id=1078
+It supports :bind_string_as_nchar only for now.
 
-* Fixed issues
+### {OCI8.properties}[:bind\_string\_as\_nchar] is added.
 
-  - Fix InvalidHandle errors on Rails.
+You need to set "`OCI8.properties[:bind_string_as_nchar] = true`"
+if the database character set is not UTF-8 and 'NCHAR'/'NVARCHAR2' columns
+contain characters which cannot be converted to the database character set.
+
+See: {http://rubyforge.org/forum/forum.php?thread\_id=48838&forum\_id=1078}
+
+Fixed issues
+------------
+
+-   Fix InvalidHandle errors on Rails.
+
     (reported by Jordan Curzon and Aaron Qian)
-    See: http://rubyforge.org/forum/forum.php?thread_id=49751&forum_id=1078
 
-  - Raise "OCIError: ORA-01805: possible error in date/time operation"
+    See: {http://rubyforge.org/forum/forum.php?thread\_id=49751&forum\_id=1078}
+
+-   Raise "OCIError: ORA-01805: possible error in date/time operation"
     when Oracle 11gR2's client and server timezone versions are not same
     instead of raising a exception "undefined method `*' for nil:NilClass."
-    See: http://rubyforge.org/forum/forum.php?thread_id=49102&forum_id=1078
 
-  - Fix unexpectedly disconnect when failed-logon connections is GC'ed
+    See: {http://rubyforge.org/forum/forum.php?thread\_id=49102&forum\_id=1078}
+
+-   Fix unexpectedly disconnect when failed-logon connections is GC'ed
     and the connection object's address is accidentally same with
     an alive connection.
 
-  - Fix segmentation fault when calling OCI8::Cursor#[] for
-    closed statement object's (reported by Hugo L. Borges)
+-   Fix segmentation fault when calling {OCI8::Cursor#[]} for
+    closed statement objects.
 
-  - Fix a bug that a string is bound to RAW.
-    Its encoding had been convertd to OCI.encoding incorrectly.
+    (reported by Hugo L. Borges)
 
-  - Fix memory leaks when temporary lobs are used.
+-   Fix a bug that a string is bound to RAW.
+    Its encoding had been convertd to {OCI.encoding} incorrectly.
 
-  - Fix a problem to assign NULL bind value to object type bind variables.
+-   Fix memory leaks when temporary lobs are used.
+
+-   Fix a problem to assign 'NULL' bind value to object type bind variables.
+
     (reported by Raimonds Simanovskis)
 
-  - Support LOB datatypes in object type.
+-   Support LOB datatypes in object type.
+
     (reported by Michael Sexton)
 
-  - Fix to compile on cygwin. The declaration of 'boolean' in Oracle
+-   Fix to compile on cygwin. The declaration of 'boolean' in Oracle
     conflicts with that of latest cygwin.
+
     (reported by Don Hill).
 
-  - Fix to complie for the 32-bit ruby which was compiled on x86_64 linux
+-   Fix to complie for the 32-bit ruby which was compiled on x86\_64 linux
     and configured without '--build', '--host' nor '--target'.
-    The RUBY_PLATFORM is 'x86_64-linux' even though the ruby is 32-bit.
+    The 'RUBY_PLATFORM' is 'x86_64-linux' even though the ruby is 32-bit.
+
     (reported by Jason Renschler)
 
-  - Fix wrong dependencies in Makefile when running 'make -jNNN (where NNN >= 2)'
+-   Fix wrong dependencies in Makefile when running 'make -jNNN (where NNN >= 2)'
+
     (contributed by Alyano Alyanos. See bug #28129 on rubyforge.)
 
-  - Fix to compile on HP-UX. Duplicated const qualifiers prevented HP-UX cc
-    from compiling. (reported by Sebastian YEPES)
+-   Fix to compile on HP-UX. Duplicated const qualifiers prevented HP-UX cc
+    from compiling.
 
-2.0.4:
+    (reported by Sebastian YEPES)
 
-* New Features
+2.0.4
+=====
 
-  - OCI8.error_message(message_no) -> string
+New Features
+------------
 
-    Gets the Oracle error message specified by message id.
-    Its language depends on NLS_LANGUAGE.
+### {OCI8.error_message} is added.
 
-    Note: This method is unavailable if the Oracle client
-          version is 8.0.
+Gets the Oracle error message specified by message id.
+Its language depends on 'NLS_LANGUAGE'.
 
-      # When NLS_LANG is AMERICAN_AMERICA.AL32UTF8
-      OCI8.error_message(1)
-      # => "ORA-00001: unique constraint (%s.%s) violated"
+Note: This method is unavailable if the Oracle client version is 8.0.
 
-      # When NLS_LANG is FRENCH_FRANCE.AL32UTF8
-      OCI8.error_message(1)
-      # => "ORA-00001: violation de contrainte unique (%s.%s)"
+    # When NLS_LANG is AMERICAN_AMERICA.AL32UTF8
+    OCI8.error_message(1)
+    # => "ORA-00001: unique constraint (%s.%s) violated"
 
-  - OraNumber#dump -> string
+    # When NLS_LANG is FRENCH_FRANCE.AL32UTF8
+    OCI8.error_message(1)
+    # => "ORA-00001: violation de contrainte unique (%s.%s)"
 
-    Returns OraNumber's internal representation whose format
-    is same with the return value of Oracle SQL function DUMP().
+### {OraNumber#dump} is added.
+
+Returns {OraNumber}'s internal representation whose format
+is same with the return value of Oracle SQL function DUMP().
   
-      OraNumber.new(100).dump #=> "Typ=2 Len=2: 194,2"
-      OraNumber.new(123).dump #=> "Typ=2 Len=3: 194,2,24"
-      OraNumber.new(0.1).dump #=> "Typ=2 Len=2: 192,11"
+    OraNumber.new(100).dump #=> "Typ=2 Len=2: 194,2"
+    OraNumber.new(123).dump #=> "Typ=2 Len=3: 194,2,24"
+    OraNumber.new(0.1).dump #=> "Typ=2 Len=2: 192,11"
 
-* Fixed issues
+Fixed issues
+------------
 
-  - Fractional second part is lost when ruby's Time instance is bound
+-   Fractional second part is lost when ruby's Time instance is bound
     to Oracle datatype TIMESTAMP.
+
     (reported by Raimonds Simanovskis)
 
-  - OraNumber#to_i and OraNumber#to_s fail when its scale is larger
+-   {OraNumber#to\_i} and {OraNumber#to\_s} fail when its scale is larger
     than 38.
+
     (reported by Raimonds Simanovskis)
 
-  - Memory leak about 30 bytes per one place holder for object type.
- 
-  - Segmentation fault when a collection of string is bound.
+-   Memory leak about 30 bytes per one place holder for object type.
+
+-   Segmentation fault when a collection of string is bound.
+
     (reported by Raimonds Simanovskis)
 
-  - Segmentation fault when GC starts while initializing a bind
+-   Segmentation fault when GC starts while initializing a bind
     object for object type.
+
     (reported by Remi Gagnon)
 
-  - Segmentation fault when OCI8::Cursor#fetch is called prior to
-    OCI8::Cursor#exec.
+-   Segmentation fault when OCI8::Cursor#fetch is called prior to
+    {OCI8::Cursor#exec}.
 
-  - Detailed error message is not reported when PL/SQL NO_DATA_FOUND
+-   Detailed error message is not reported when 'PL/SQL NO_DATA_FOUND'
     exception is raised.
+
     (reported by Raimonds Simanovskis)
 
-2.0.3:
+2.0.3
+=====
 
-* Incompatible Changes
+Incompatible Changes
+--------------------
 
-  - Number column in a SQL statement
+### Number column in a SQL statement
 
-    Changes the default data type for number column which fit neither
-    Integer nor Float from OraNumber to BigDecimal.
+Changes the default data type for number column which fit neither
+Integer nor Float from {OraNumber} to BigDecimal.
 
-      conn.exec("select 1.0 from dual") do |row|
-        p row[0] # => BigDecimal("1") if the ruby-oci8 version is 2.0.3.
-                 # => OraNumber(1) if the version is 2.0.2.
-      end
+    conn.exec("select 1.0 from dual") do |row|
+      p row[0] # => BigDecimal("1") if the ruby-oci8 version is 2.0.3.
+               # => OraNumber(1) if the version is 2.0.2.
+    end
 
-  - Priority of OraNumber within numerical types
+### Priority of OraNumber within numerical types
 
-    The return types of basic arithmetic operations with other numerical
-    types are changed.
+The return types of basic arithmetic operations with other numerical
+types are changed.
 
-    2.0.3:
-      OraNumber + Integer    => OraNumber  (OraNumber wins.)
-      OraNumber + Float      => Float      (OraNumber loses.)
-      OraNumber + Rational   => Rational   (OraNumber loses.)
-      OraNumber + BigDecimal => BigDecimal (OraNumber loses.)
+2.0.3:
 
-    2.0.2:
-      OraNumber + Integer    => OraNumber  (OraNumber wins always.)
-      OraNumber + Float      => OraNumber
-      OraNumber + Rational   => OraNumber
-      OraNumber + BigDecimal => OraNumber
+    OraNumber + Integer    => OraNumber  (OraNumber wins.)
+    OraNumber + Float      => Float      (OraNumber loses.)
+    OraNumber + Rational   => Rational   (OraNumber loses.)
+    OraNumber + BigDecimal => BigDecimal (OraNumber loses.)
 
-  - Interval day to second
+2.0.2:
 
-    The retrived value of Oracle data type "interval day to second"
-    was changed from the number of days as a Rational to the number
-    of seconds as a Float by default.
-    Use OCI8::BindType::IntervalDS.unit = :day to make it compatible
-    with the previous versions.
+    OraNumber + Integer    => OraNumber  (OraNumber wins always.)
+    OraNumber + Float      => OraNumber
+    OraNumber + Rational   => OraNumber
+    OraNumber + BigDecimal => OraNumber
 
-      conn.exec("select to_dsinterval('0 00:00:01') from dual") do |row|
-        p row[0] # => 1.0 if the version is 2.0.3 and
-                 #    OCI8::BindType::IntervalDS.unit is :second.
-                 # => (1/86400) if the version is 2.0.3 and
-		 #    OCI8::BindType::IntervalDS.unit is :day or
-		 #    the version is 2.0.2.
-      end
+### Interval day to second
 
-  - Date, timestamp, timestamp with time zone data types and ruby 1.9.2
+The retrived value of Oracle data type "interval day to second"
+was changed from the number of days as a Rational to the number
+of seconds as a Float by default.
+Use 'OCI8::BindType::IntervalDS.unit = :day' to make it compatible
+with the previous versions.
 
-    These data types are retrived always as Time values when the
-    ruby version is 1.9.2 because the Time class is enhanced to
-    represent any time zone and is free from year 2038 problem.
+    conn.exec("select to_dsinterval('0 00:00:01') from dual") do |row|
+      p row[0] # => 1.0 if the version is 2.0.3 and
+               #    OCI8::BindType::IntervalDS.unit is :second.
+               # => (1/86400) if the version is 2.0.3 and
+               #    OCI8::BindType::IntervalDS.unit is :day or
+               #    the version is 2.0.2.
+    end
 
-    Prior to ruby 1.9.2, if the time cannot be represented by
-    Unix time or the time zone is neither utc nor local, they are
-    retrived as DateTime values.
+### Date, timestamp, timestamp with time zone data types and ruby 1.9.2
 
-  - Non-blocking mode and ruby 1.9
+These data types are retrived always as Time values when the
+ruby version is 1.9.2 because the Time class is enhanced to
+represent any time zone and is free from year 2038 problem.
 
-    non-blocking mode is enabled by default when the ruby is 1.9.
+Prior to ruby 1.9.2, if the time cannot be represented by
+Unix time or the time zone is neither utc nor local, they are
+retrived as DateTime values.
 
-* New Features
+### Non-blocking mode and ruby 1.9
 
-  - BigDecimal and Rational are availabe as bind values.
+Non-blocking mode is enabled by default when the ruby is 1.9.
 
-  - New methods OCI8#module=, OCI8#action= and OCI8#client_info= are added.
+New Features
+------------
 
-    These methods change the module name, the action name and the client_info
-    in the current session respectively.
+### BigDecimal and Rational are availabe as bind values.
 
-    After Oracle 10g client, these don't perform network round trips.
-    The change is reflected to the server by the next round trip such as
-    OCI8#exec, OCI8#ping, etc.
+### New methods {OCI8#module=}, {OCI8#action=} and {OCI8#client_info=} are added.
 
-    Prior to Oracle 10g client, these call PL/SQL functions such as
-    DBMS_APPLICATION_INFO.SET_MODULE, DBMS_APPLICATION_INFO.SET_ACTION,
-    and DBMS_APPLICATION_INFO.SET_CLIENT_INFO internally.
-    The change is reflected immediately by a network round trip.
+These methods change the module name, the action name and the client_info
+in the current session respectively.
 
-  - OCI8::BindType.default_timezone
+After Oracle 10g client, these don't perform network round trips.
+The change is reflected to the server by the next round trip such as
+{OCI8#exec}, {OCI8#ping}, etc.
 
-    The default time zone of Time or DateTime values.
-    This parameter is used only when
-    (1) date values are fetched and the Oracle client version is 8.x
+Prior to Oracle 10g client, these call PL/SQL functions such as
+`DBMS_APPLICATION_INFO.SET_MODULE`, `DBMS_APPLICATION_INFO.SET_ACTION`,
+and `DBMS_APPLICATION_INFO.SET_CLIENT_INFO` internally.
+The change is reflected immediately by a network round trip.
+
+### {OCI8::BindType.default_timezone}
+
+The default time zone of Time or DateTime values. This parameter is used only when
+
+* date values are fetched and the Oracle client version is 8.x
+
     or
-    (2) object types have date data type attributes.
 
-    Note that if the Oracle client version is 9i or upper, the time
-    zone is determined by the session time zone. The default value
-    is local time zone. You can change it to GMT by executing the
-    following SQL statement for each connection.
+* object types have date data type attributes.
 
-       alter session set time_zone = '00:00'
+Note that if the Oracle client version is 9i or upper, the time
+zone is determined by the session time zone. The default value
+is local time zone. You can change it to GMT by executing the
+following SQL statement for each connection.
 
-* Other specification changes
+    alter session set time_zone = '00:00'
 
-  - Add a global function OraNumber(obj) as a shortcut of OraNumber.new(obj)
+Note: The session time zone is set by the environment variable TZ from
+ruby-oci8 2.1.0.
+
+Other specification changes
+---------------------------
+
+-   Add a global function OraNumber(obj) as a shortcut of OraNumber.new(obj)
     as Rational and BigDecimal do.
 
-  - Fix to accept nil attribute in object type's
+-   Fix to accept nil attribute in object type's
     constructors. This works only for simple data types such as number,
     string. But it doesn't for complex types such as object types.
     (requested by Remi Gagnon)
 
-  - add DATE datatype support in object types.
+- add DATE datatype support in object types.
 
-  - Change OCI8::LOB#write to accept an object which is not a String and
+-   Change {OCI8::LOB#write} to accept an object which is not a String and
     doesn't respond to 'to_str' as IO#write does.
     (requested by Christopher Jones)
 
-  - Change the initial polling interval of
+-   Change the initial polling interval of
     non-blocking mode for ruby 1.8 from 100 msec to 10 msec, which
     is same with ruby-oci8 1.0.
 
-* Fixed installation issues.
+Fixed installation issues
+-------------------------
 
-  - Fix oraconf.rb for ruby 1.8.5 with Oracle 8.x which needs some object
+-   Fix oraconf.rb for ruby 1.8.5 with Oracle 8.x which needs some object
     files to link with.
+
     (reported by Jayson Cena)
 
-  - Fix oraconf.rb for ruby 1.9.2 preview1.
+-   Fix oraconf.rb for ruby 1.9.2 preview1.
+
     (pointed by Raimonds Simanovskis)
 
-  - Fix oraconf.rb to compile for AIX instant clients.
+-   Fix oraconf.rb to compile for AIX instant clients.
+
     (reported by Kazuya Teramoto)
 
-2.0.2:
+2.0.2
+=====
 
-* add new methods
-  - OCI8#select_one(sql, *bindvars)  -> first_row
+*   add new methods
+    -   {OCI8#select_one}
 
-  - OCI8#ping   -> true or false
+    -   {OCI8#ping}   -> true or false
 
-    Verifies that the Oracle connection is alive.
-    OCI8#ping also can be used to flush all the pending OCI
-    client-side calls to the server if any exist.
+        Verifies that the Oracle connection is alive.
+        {OCI8#ping} also can be used to flush all the pending OCI
+        client-side calls to the server if any exist.
 
-  - OCI8#client_identifier = client_id
+    -   {OCI8#client\_identifier=}client\_id
 
-    Look at the following link to know what is the client identifier.
-      http://it.toolbox.com/blogs/database-solutions/oracle-session-tracing-part-i-16356
+        Look at the following link to know what is the client identifier.
+        {http://it.toolbox.com/blogs/database-solutions/oracle-session-tracing-part-i-16356}
 
-    Note that the specified identifier doesn't change the v$session
-    immediately. It is done by the next network round trip
-    such as OCI8#exec or OCI8#ping.
+        Note that the specified identifier doesn't change the v$session
+        immediately. It is done by the next network round trip
+        such as OCI8#exec or OCI8#ping.
 
-* fix problems when compiling with Oracle 9.2 and 8.0.
-  (reported by Axel Reinhold)
+*   fix problems when compiling with Oracle 9.2 and 8.0.
 
-* [dbi] fix to pass a newly added sanity check in dbi 0.4.1.
-  (reported by Dirk Herzhauser)
+    (reported by Axel Reinhold)
 
-* fix an error when executing "select NULL from dual".
-  http://rubyforge.org/forum/forum.php?thread_id=32468&forum_id=1078
-  (contributed by Raimonds Simanovskis)
+*   [dbi] fix to pass a newly added sanity check in dbi 0.4.1.
 
-* [ruby 1.9] fix OCI8::BLOB to read/write binary. Prior to 2.0.1,
-  it was treated as text tagged with NLS_LANG encoding.
+    (reported by Dirk Herzhauser)
 
-* [ruby 1.9] fix to bind string data by the length got from String#bytesize
-  converted to OCI8.encoding, not by String#size.
+*   fix an error when executing "select NULL from dual".
 
-2.0.1:
+    {http://rubyforge.org/forum/forum.php?thread\_id=32468&forum\_id=1078}
+    (contributed by Raimonds Simanovskis)
 
-* release a binary gem for Windows, which contains libraries for both
-  ruby 1.8 and ruby 1.9.1.
-* add OCI8#oracle_server_version.
-* fix bugs when fetching and binding time objects.
+*   [ruby 1.9] fix OCI8::BLOB to read/write binary. Prior to 2.0.1,
+
+    it was treated as text tagged with 'NLS_LANG' encoding.
+
+*   [ruby 1.9] fix to bind string data by the length got from String#bytesize
+    converted to {OCI8.encoding}, not by String#size.
+
+2.0.1
+=====
+
+*   release a binary gem for Windows, which contains libraries for both
+    ruby 1.8 and ruby 1.9.1.
+*   add {OCI8#oracle\_server\_version}.
+*   fix bugs when fetching and binding time objects.


From nobody at rubyforge.org  Tue Apr  3 11:08:38 2012
From: nobody at rubyforge.org (nobody at rubyforge.org)
Date: Tue,  3 Apr 2012 11:08:38 +0000 (UTC)
Subject: [ruby-oci8-commit] [499] trunk/ruby-oci8: change OCI8::Math::*'s
	comments for yard.
Message-ID: <20120403110838.3A40D26303E@rubyforge.org>

Revision: 499
Author:   kubo
Date:     2012-04-03 11:08:37 +0000 (Tue, 03 Apr 2012)
Log Message:
-----------
change OCI8::Math::*'s comments for yard.

Modified Paths:
--------------
    trunk/ruby-oci8/ChangeLog
    trunk/ruby-oci8/ext/oci8/oci8.h
    trunk/ruby-oci8/ext/oci8/ocinumber.c

Modified: trunk/ruby-oci8/ChangeLog
===================================================================
--- trunk/ruby-oci8/ChangeLog	2012-04-02 13:47:34 UTC (rev 498)
+++ trunk/ruby-oci8/ChangeLog	2012-04-03 11:08:37 UTC (rev 499)
@@ -1,3 +1,7 @@
+2012-04-03  KUBO Takehiro  <kubo at jiubao.org>
+	* ext/oci8/oci8.h, ext/oci8/ocinumber.c: change OCI8::Math::*'s comments
+	    for yard.
+
 2012-04-02  KUBO Takehiro  <kubo at jiubao.org>
 	* NEWS: change the text format to markdown.
 

Modified: trunk/ruby-oci8/ext/oci8/oci8.h
===================================================================
--- trunk/ruby-oci8/ext/oci8/oci8.h	2012-04-02 13:47:34 UTC (rev 498)
+++ trunk/ruby-oci8/ext/oci8/oci8.h	2012-04-03 11:08:37 UTC (rev 499)
@@ -521,13 +521,21 @@
 /* ocinumber.c */
 extern int oci8_float_conversion_type_is_ruby;
 void Init_oci_number(VALUE mOCI, OCIError *errhp);
+/* OraNumber (ruby object) -> OCINumber (C datatype) */
 OCINumber *oci8_get_ocinumber(VALUE num);
+/* OCINumber (C datatype) -> OraNumber (ruby object) */
 VALUE oci8_make_ocinumber(OCINumber *s, OCIError *errhp);
+/* OCINumber (C datatype) -> Integer (ruby object) */
 VALUE oci8_make_integer(OCINumber *s, OCIError *errhp);
+/* OCINumber (C datatype) -> Float (ruby object) */
 VALUE oci8_make_float(OCINumber *s, OCIError *errhp);
+/* Numeric (ruby object) -> OCINumber (C datatype) */
 OCINumber *oci8_set_ocinumber(OCINumber *result, VALUE self, OCIError *errhp);
+/* Numeric (ruby object) -> OCINumber (C datatype) as an integer */
 OCINumber *oci8_set_integer(OCINumber *result, VALUE self, OCIError *errhp);
+/* OCINumber (C datatype) -> double (C datatype) */
 double oci8_onum_to_dbl(OCINumber *s, OCIError *errhp);
+/* double (C datatype) -> OCINumber (C datatype) */
 OCINumber *oci8_dbl_to_onum(OCINumber *result, double dbl, OCIError *errhp);
 
 /* ocidatetim.c */

Modified: trunk/ruby-oci8/ext/oci8/ocinumber.c
===================================================================
--- trunk/ruby-oci8/ext/oci8/ocinumber.c	2012-04-02 13:47:34 UTC (rev 498)
+++ trunk/ruby-oci8/ext/oci8/ocinumber.c	2012-04-03 11:08:37 UTC (rev 499)
@@ -112,7 +112,9 @@
     return obj;
 }
 
-/* construct an ruby object(OCI::Number) from C structure (OCINumber). */
+/*
+ * OCINumber (C datatype) -> OraNumber (ruby object)
+ */
 VALUE oci8_make_ocinumber(OCINumber *s, OCIError *errhp)
 {
     VALUE obj;
@@ -123,6 +125,9 @@
     return obj;
 }
 
+/*
+ * OCINumber (C datatype) -> Integer (ruby object)
+ */
 VALUE oci8_make_integer(OCINumber *s, OCIError *errhp)
 {
     signed long sl;
@@ -141,12 +146,17 @@
     rb_raise(eOCIException, "Invalid internal number format: %s", buf);
 }
 
+/*
+ * OCINumber (C datatype) -> Float (ruby object)
+ */
 VALUE oci8_make_float(OCINumber *s, OCIError *errhp)
 {
     return rb_float_new(oci8_onum_to_dbl(s, errhp));
 }
 
-/* fill C structure (OCINumber) from a string. */
+/*
+ * String (ruby object) -> OCINumber (C datatype)
+ */
 static void set_oci_number_from_str(OCINumber *result, VALUE str, VALUE fmt, VALUE nls_params, OCIError *errhp)
 {
     oratext *fmt_ptr;
@@ -190,8 +200,11 @@
                              result));
 }
 
-/* fill C structure (OCINumber) from a numeric object. */
-/* 1 - success, 0 - error */
+/*
+ * Numeric (ruby object) -> OCINumber (C datatype)
+ *
+ * @return 1 on success. Otherwise, 0.
+ */
 static int set_oci_number_from_num(OCINumber *result, VALUE num, int force, OCIError *errhp)
 {
     signed long sl;
@@ -287,6 +300,9 @@
     return 0;
 }
 
+/*
+ * Numeric (ruby object) -> OCINumber (C datatype)
+ */
 OCINumber *oci8_set_ocinumber(OCINumber *result, VALUE self, OCIError *errhp)
 {
     set_oci_number_from_num(result, self, 1, errhp);
@@ -294,6 +310,9 @@
 }
 #define TO_OCINUM oci8_set_ocinumber
 
+/*
+ * Numeric (ruby object) -> OCINumber (C datatype) as an integer
+ */
 OCINumber *oci8_set_integer(OCINumber *result, VALUE self, OCIError *errhp)
 {
     OCINumber work;
@@ -303,6 +322,9 @@
     return result;
 }
 
+/*
+ * OCINumber (C datatype) -> double (C datatype)
+ */
 double oci8_onum_to_dbl(OCINumber *s, OCIError *errhp)
 {
     if (oci8_float_conversion_type_is_ruby) {
@@ -330,6 +352,9 @@
     }
 }
 
+/*
+ * double (C datatype) -> OCINumber (C datatype)
+ */
 OCINumber *oci8_dbl_to_onum(OCINumber *result, double dbl, OCIError *errhp)
 {
     if (isnan(dbl)) {
@@ -361,10 +386,15 @@
 
 /*
  *  call-seq:
- *     OCI8::Math.atan2(y, x) -> oranumber
+ *    atan2(y, x)
  *
- *  Computes the arc tangent given <i>y</i> and <i>x</i>. Returns
- *  -PI..PI.
+ *  Computes the principal value of the arc tangent of <i>y/x</i>,
+ *  using the signs of both arguments to determine the quadrant of the
+ *  return value.
+ *
+ *  @param [Numeric] y
+ *  @param [Numeric] x
+ *  @return [OraNumber]  Computed value in the range [-{PI}, {PI}]
  */
 static VALUE omath_atan2(VALUE self, VALUE Ycoordinate, VALUE Xcoordinate)
 {
@@ -397,10 +427,12 @@
 
 /*
  *  call-seq:
- *     OCI8::Math.cos(x) -> oranumber
+ *     cos(x)
  *
- *  Computes the cosine of <i>x</i> (expressed in radians). Returns
- *  -1..1.
+ *  Computes the cosine of <i>x</i>, measured in radians.
+ *
+ *  @param [Numeric] x
+ *  @return [OraNumber]  Computed value in the range [-1, 1]
  */
 static VALUE omath_cos(VALUE obj, VALUE radian)
 {
@@ -414,10 +446,12 @@
 
 /*
  *  call-seq:
- *     OCI8::Math.sin(x)    -> oranumber
+ *     sin(x)
  *
- *  Computes the sine of <i>x</i> (expressed in radians). Returns
- *  -1..1.
+ *  Computes the sine of <i>x</i>, measured in radians.
+ *
+ *  @param [Numeric] x
+ *  @return [OraNumber]  Computed value in the range [-1, 1]
  */
 static VALUE omath_sin(VALUE obj, VALUE radian)
 {
@@ -431,9 +465,12 @@
 
 /*
  *  call-seq:
- *     OCI8::Math.tan(x)    -> oranumber
+ *     tan(x)
  *
- *  Returns the tangent of <i>x</i> (expressed in radians).
+ *  Computes the tangent of <i>x</i>, measured in radians.
+ *
+ *  @param [Numeric] x
+ *  @return [OraNumber]
  */
 static VALUE omath_tan(VALUE obj, VALUE radian)
 {
@@ -447,9 +484,12 @@
 
 /*
  *  call-seq:
- *     OCI8::Math.acos(x)    -> oranumber
+ *     acos(x)
  *
- *  Computes the arc cosine of <i>x</i>. Returns 0..PI.
+ *  Computes the principal value of the arc cosine of <i>x</i>.
+ *
+ *  @param [Numeric] x
+ *  @return [OraNumber]  Computed value in the range [0, {PI}]
  */
 static VALUE omath_acos(VALUE obj, VALUE num)
 {
@@ -474,9 +514,12 @@
 
 /*
  *  call-seq:
- *     OCI8::Math.asin(x)    -> oranumber
+ *     asin(x)
  *
- *  Computes the arc sine of <i>x</i>. Returns 0..PI.
+ *  Computes the principal value of the arc sine of <i>x</i>.
+ *
+ *  @param [Numeric] x
+ *  @return [OraNumber]  Computed value in the range [-{PI}/2, {PI}]/2]
  */
 static VALUE omath_asin(VALUE obj, VALUE num)
 {
@@ -501,9 +544,12 @@
 
 /*
  *  call-seq:
- *     OCI8::Math.atan(x)    -> oranumber
+ *     atan(x)
  *
- *  Computes the arc tangent of <i>x</i>. Returns -{PI/2} .. {PI/2}.
+ *  Computes the principal value of the arc tangent of their argument <i>x</i>.
+ *
+ *  @param [Numeric] x
+ *  @return [OraNumber]  Computed value in the range [-{PI}/2, {PI}/2]
  */
 static VALUE omath_atan(VALUE obj, VALUE num)
 {
@@ -517,9 +563,12 @@
 
 /*
  *  call-seq:
- *     OCI8::Math.cosh(x)    -> oranumber
+ *     cosh(x)
  *
- *  Computes the hyperbolic cosine of <i>x</i> (expressed in radians).
+ *  Computes the hyperbolic cosine of <i>x</i>.
+ *
+ *  @param [Numeric] x
+ *  @return [OraNumber]
  */
 static VALUE omath_cosh(VALUE obj, VALUE num)
 {
@@ -533,10 +582,12 @@
 
 /*
  *  call-seq:
- *     OCI8::Math.sinh(x)    -> oranumber
+ *     sinh(x)
  *
- *  Computes the hyperbolic sine of <i>x</i> (expressed in
- *  radians).
+ *  Computes the hyperbolic sine of <i>x</i>.
+ *
+ *  @param [Numeric] x
+ *  @return [OraNumber]
  */
 static VALUE omath_sinh(VALUE obj, VALUE num)
 {
@@ -550,10 +601,12 @@
 
 /*
  *  call-seq:
- *     OCI8::Math.tanh()    -> oranumber
+ *     tanh(x)
  *
- *  Computes the hyperbolic tangent of <i>x</i> (expressed in
- *  radians).
+ *  Computes the hyperbolic tangent of <i>x</i>.
+ *
+ *  @param [Numeric] x
+ *  @return [OraNumber]
  */
 static VALUE omath_tanh(VALUE obj, VALUE num)
 {
@@ -567,9 +620,12 @@
 
 /*
  *  call-seq:
- *     OCI8::Math.exp(x)    -> oranumber
+ *     exp(x)
  *
- *  Returns e**x.
+ *  Computes the base- <i>e</i> exponential of <i>x</i>.
+ *
+ *  @param [Numeric] x
+ *  @return [OraNumber]
  */
 static VALUE omath_exp(VALUE obj, VALUE num)
 {
@@ -582,12 +638,16 @@
 }
 
 /*
- *  call-seq:
- *     OCI8::Math.log(numeric)    -> oranumber
- *     OCI8::Math.log(numeric, base_num)  -> oranumber
+ *  @overload log(x)
+ *    Computes the natural logarithm of <i>x</i>.
+ *    @param [Numeric] x
+ *    @return [OraNumber]
  *
- *  Returns the natural logarithm of <i>numeric</i> for one argument.
- *  Returns the base <i>base_num</i> logarithm of <i>numeric</i> for two arguments.
+ *  @overload log(x, y)
+ *    Computes the base <i>y</I> logarithm of <i>x</i>.
+ *    @param [Numeric] x
+ *    @param [Numeric] y
+ *    @return [OraNumber]
  */
 static VALUE omath_log(int argc, VALUE *argv, VALUE obj)
 {
@@ -620,9 +680,12 @@
 
 /*
  *  call-seq:
- *     OCI8::Math.log10(numeric)    -> oranumber
+ *     log10(x)
  *
- *  Returns the base 10 logarithm of <i>numeric</i>.
+ *  Computes the base 10 logarithm of <i>x</i>.
+ *
+ *  @param [Numeric] x
+ *  @return [OraNumber]
  */
 static VALUE omath_log10(VALUE obj, VALUE num)
 {
@@ -641,9 +704,12 @@
 
 /*
  *  call-seq:
- *     OCI8::Math.sqrt(numeric)    -> oranumber
+ *     sqrt(x)
  *
- *  Returns the non-negative square root of <i>numeric</i>.
+ *  Computes the square root of <i>x</i>.
+ *
+ *  @param [Numeric] x
+ *  @return [OraNumber]
  */
 static VALUE omath_sqrt(VALUE obj, VALUE num)
 {
@@ -1525,6 +1591,13 @@
     OCINumberSetPi(errhp, &num1);
     obj_PI = oci8_make_ocinumber(&num1, errhp);
 
+    /* Document-module: OCI8::Math
+     *
+     *  The <code>OCI8::Math</code> module contains module functions for basic
+     *  trigonometric and transcendental functions. Their accuracy is
+     *  same with {OraNumber}.
+     */
+
     /* The ratio of the circumference of a circle to its diameter. */
     rb_define_const(mMath, "PI", obj_PI);
 
@@ -1553,10 +1626,10 @@
     rb_define_alloc_func(cOCINumber, onum_s_alloc);
 
     /* methods of OCI::Number */
-    rb_define_method(rb_cObject, "OraNumber", onum_f_new, -1);
-    rb_define_method_nodoc(cOCINumber, "initialize", onum_initialize, -1);
-    rb_define_method_nodoc(cOCINumber, "initialize_copy", onum_initialize_copy, 1);
-    rb_define_method_nodoc(cOCINumber, "coerce", onum_coerce, 1);
+    rb_define_global_function("OraNumber", onum_f_new, -1);
+    rb_define_method(cOCINumber, "initialize", onum_initialize, -1);
+    rb_define_method(cOCINumber, "initialize_copy", onum_initialize_copy, 1);
+    rb_define_method(cOCINumber, "coerce", onum_coerce, 1);
 
     rb_include_module(cOCINumber, rb_mComparable);
 
@@ -1582,15 +1655,15 @@
     rb_define_method(cOCINumber, "to_r", onum_to_r, 0);
     rb_define_method(cOCINumber, "to_d", onum_to_d, 0);
     rb_define_method(cOCINumber, "has_decimal_part?", onum_has_decimal_part_p, 0);
-    rb_define_method_nodoc(cOCINumber, "to_onum", onum_to_onum, 0);
+    rb_define_method(cOCINumber, "to_onum", onum_to_onum, 0);
 
     rb_define_method(cOCINumber, "zero?", onum_zero_p, 0);
     rb_define_method(cOCINumber, "abs", onum_abs, 0);
     rb_define_method(cOCINumber, "shift", onum_shift, 1);
     rb_define_method(cOCINumber, "dump", onum_dump, 0);
 
-    rb_define_method_nodoc(cOCINumber, "hash", onum_hash, 0);
-    rb_define_method_nodoc(cOCINumber, "inspect", onum_inspect, 0);
+    rb_define_method(cOCINumber, "hash", onum_hash, 0);
+    rb_define_method(cOCINumber, "inspect", onum_inspect, 0);
 
     /* methods for marshaling */
     rb_define_method(cOCINumber, "_dump", onum__dump, -1);
@@ -1599,8 +1672,22 @@
     oci8_define_bind_class("OraNumber", &bind_ocinumber_vtable);
     oci8_define_bind_class("Integer", &bind_integer_vtable);
     oci8_define_bind_class("Float", &bind_float_vtable);
+
+#if 0 /* for rdoc/yard */
+    oci8_cOCIHandle = rb_define_class("OCIHandle", rb_cObject);
+    cOCI8 = rb_define_class("OCI8", oci8_cOCIHandle);
+    mOCI8BindType = rb_define_module_under(cOCI8, "BindType");
+    cOCI8BindTypeBase = rb_define_class_under(mOCI8BindType, "Base", oci8_cOCIHandle);
+
+    dummy1 = rb_define_class_under(mOCI8BindType, "OraNumber", cOCI8BindTypeBase);
+    dummy2 = rb_define_class_under(mOCI8BindType, "Integer", cOCI8BindTypeBase);
+    dummy3 = rb_define_class_under(mOCI8BindType, "Float", cOCI8BindTypeBase);
+#endif
 }
 
+/*
+ * OraNumber (ruby object) -> OCINumber (C datatype)
+ */
 OCINumber *oci8_get_ocinumber(VALUE num)
 {
     if (!rb_obj_is_kind_of(num, cOCINumber)) {


From nobody at rubyforge.org  Thu Apr  5 13:36:06 2012
From: nobody at rubyforge.org (nobody at rubyforge.org)
Date: Thu,  5 Apr 2012 13:36:06 +0000 (UTC)
Subject: [ruby-oci8-commit] [500] trunk/ruby-oci8: revise OraNumber's
	comments.
Message-ID: <20120405133607.0702C3B002@rubyforge.org>

Revision: 500
Author:   kubo
Date:     2012-04-05 13:36:06 +0000 (Thu, 05 Apr 2012)
Log Message:
-----------
revise OraNumber's comments.

Modified Paths:
--------------
    trunk/ruby-oci8/ChangeLog
    trunk/ruby-oci8/ext/oci8/ocinumber.c
    trunk/ruby-oci8/lib/oci8/oci8.rb

Modified: trunk/ruby-oci8/ChangeLog
===================================================================
--- trunk/ruby-oci8/ChangeLog	2012-04-03 11:08:37 UTC (rev 499)
+++ trunk/ruby-oci8/ChangeLog	2012-04-05 13:36:06 UTC (rev 500)
@@ -1,3 +1,6 @@
+2012-04-05  KUBO Takehiro  <kubo at jiubao.org>
+	* ext/oci8/ocinumber.c, lib/oci8/oci8.rb: revise OraNumber's comments.
+
 2012-04-03  KUBO Takehiro  <kubo at jiubao.org>
 	* ext/oci8/oci8.h, ext/oci8/ocinumber.c: change OCI8::Math::*'s comments
 	    for yard.

Modified: trunk/ruby-oci8/ext/oci8/ocinumber.c
===================================================================
--- trunk/ruby-oci8/ext/oci8/ocinumber.c	2012-04-03 11:08:37 UTC (rev 499)
+++ trunk/ruby-oci8/ext/oci8/ocinumber.c	2012-04-05 13:36:06 UTC (rev 500)
@@ -2,7 +2,7 @@
 /*
  *  ocinumber.c
  *
- * Copyright (C) 2005-2011 KUBO Takehiro <kubo at jiubao.org>
+ * Copyright (C) 2005-2012 KUBO Takehiro <kubo at jiubao.org>
  *
  */
 #include "oci8.h"
@@ -385,6 +385,14 @@
 }
 
 /*
+ *  Document-module: OCI8::Math
+ *
+ *  The <code>OCI8::Math</code> module contains module functions for basic
+ *  trigonometric and transcendental functions. Their accuracy is
+ *  same with {OraNumber}.
+ */
+
+/*
  *  call-seq:
  *    atan2(y, x)
  *
@@ -639,12 +647,16 @@
 
 /*
  *  @overload log(x)
+ *
  *    Computes the natural logarithm of <i>x</i>.
+ *
  *    @param [Numeric] x
  *    @return [OraNumber]
  *
  *  @overload log(x, y)
+ *
  *    Computes the base <i>y</I> logarithm of <i>x</i>.
+ *
  *    @param [Numeric] x
  *    @param [Numeric] y
  *    @return [OraNumber]
@@ -729,12 +741,39 @@
     return oci8_make_ocinumber(&r, errhp);
 }
 
+/*
+ *  Document-class: OraNumber
+ *
+ *  OraNumber is a ruby representation of
+ *  {http://docs.oracle.com/cd/E11882_01/server.112/e17118/sql_elements001.htm#sthref118 Oracle NUMBER data type}.
+ *  without precision and scale designators.
+ */
 
 /*
  *  call-seq:
- *     OraNumber(obj)   -> oranumber
+ *    OraNumber(expr = nil, fmt = nil, nlsparam = nil)
  *
- *  Returns a new <code>OraNumber</code>.
+ *  Converts <i>expr</i> to a value of OraNumber. The <i>expr</i> can be a Numeric value
+ *  or a String value. If it is a String value, optional <i>fmt</i> and <i>nlsparam</i>.
+ *  is used as {http://docs.oracle.com/cd/E11882_01/server.112/e17118/functions211.htm Oracle SQL function TO_NUMBER}
+ *  does.
+ *
+ *  @example
+ *    # Numeric expr
+ *    OraNumber(123456.789)   # -> 123456.789
+ *    # String expr
+ *    OraNumber('123456.789') # -> 123456.789
+ *    # String expr with fmt
+ *    OraNumber('123,456.789', '999,999,999.999') # -> 123456.789
+ *    # String expr with fmt and nlsparam
+ *    OraNumber('123.456,789', '999G999G999D999',  "NLS_NUMERIC_CHARACTERS = ',.'") # -> 123456.789
+ *
+ *  @param [String, Numeric] expr
+ *  @param [String]          fmt
+ *  @param [String]          nlsparam
+ *  @return [OraNumber]
+ *
+ *  @since 2.0.3
  */
 static VALUE onum_f_new(int argc, VALUE *argv, VALUE self)
 {
@@ -743,6 +782,29 @@
     return obj;
 }
 
+/*
+ *  call-seq:
+ *    initialize(expr = nil, fmt = nil, nlsparam = nil)
+ *
+ *  Creates a value of OraNumber from <i>expr</i>. The <i>expr</i> can be a Numeric value
+ *  or a String value. If it is a String value, optional <i>fmt</i> and <i>nlsparam</i>
+ *  is used as {http://docs.oracle.com/cd/E11882_01/server.112/e17118/functions211.htm Oracle SQL function TO_NUMBER}
+ *  does.
+ *
+ *  @example
+ *    # Numeric expr
+ *    OraNumber.new(123456.789)   # -> 123456.789
+ *    # String expr
+ *    OraNumber.new('123456.789') # => #<OraNumber:123456.789>
+ *    # String expr with fmt
+ *    OraNumber.new('123,456.789', '999,999,999.999') # => #<OraNumber:123456.789>
+ *    # String expr with fmt and nlsparam
+ *    OraNumber.new('123.456,789', '999G999G999D999', "NLS_NUMERIC_CHARACTERS = ',.'") # => #<OraNumber:123456.789>
+ *
+ *  @param [String, Numeric] expr
+ *  @param [String]          fmt
+ *  @param [String]          nlsparam
+ */
 static VALUE onum_initialize(int argc, VALUE *argv, VALUE self)
 {
     OCIError *errhp = oci8_errhp;
@@ -760,6 +822,17 @@
     return Qnil;
 }
 
+/*
+ *  call-seq:
+ *    initialize_copy(obj)
+ *
+ *  Replaces <i>self</i> with <i>obj</i>. <code>Object#clone</code> and <code>Object#dup</code>
+ *  call this method to copy data unknown by the ruby interpreter.
+ *
+ *  @param [OraNumber] obj
+ *
+ *  @private
+ */
 static VALUE onum_initialize_copy(VALUE lhs, VALUE rhs)
 {
     if (!RTEST(rb_obj_is_instance_of(rhs, CLASS_OF(lhs)))) {
@@ -770,6 +843,9 @@
     return lhs;
 }
 
+/*
+ *  @private
+ */
 static VALUE onum_coerce(VALUE self, VALUE other)
 {
     signed long sl;
@@ -797,10 +873,12 @@
 }
 
 /*
- *  call-seq:
- *     -onum   -> oranumber
+ *  Returns a negated value of <i>self</i>
  *
- *  Returns a negated <code>OraNumber</code>.
+ *  @example
+ *    -OraNumber(2)  # =>  #<OraNumber:-2>
+ *
+ *  @return [OraNumber]
  */
 static VALUE onum_neg(VALUE self)
 {
@@ -811,12 +889,20 @@
     return oci8_make_ocinumber(&r, errhp);
 }
 
-
 /*
  *  call-seq:
- *    onum + other    -> number
+ *    self + other
  *
- *  Returns the sum of <i>onum</i> and <i>other</i>.
+ *  Returns the sum of <i>self</i> and <i>other</i>.
+ *  When <i>other</i>'s class is Integer, it returns an OraNumber value.
+ *  Otherwise, it returns a value same with <i>other</i>'s class.
+ *
+ *  @example
+ *    OraNumber(2) + 3   # => #<OraNumber:5>
+ *    OraNumber(2) + 1.5 # => 3.5 (Float)
+ *
+ *  @param [Numeric] other
+ *  @return [Numeric]
  */
 static VALUE onum_add(VALUE lhs, VALUE rhs)
 {
@@ -847,10 +933,18 @@
 
 /*
  *  call-seq:
- *    onum - integer   -> oranumber
- *    onum - numeric   -> numeric
+ *    self - other
  *
- *  Returns the difference of <i>onum</i> and <i>other</i>.
+ *  Returns the difference of <i>self</i> and <i>other</i>.
+ *  When <i>other</i>'s class is Integer, it returns an OraNumber value.
+ *  Otherwise, it returns a value same with <i>other</i>'s class.
+ *
+ *  @example
+ *    OraNumber(2) - 3   # => #<OraNumber:-1>
+ *    OraNumber(2) - 1.5 # => 0.5 (Float)
+ *
+ *  @param [Numeric] other
+ *  @return [Numeric]
  */
 static VALUE onum_sub(VALUE lhs, VALUE rhs)
 {
@@ -881,9 +975,18 @@
 
 /*
  *  call-seq:
- *    onum * other   -> number
+ *    self * other
  *
- *  Returns the product of <i>onum</i> and <i>other</i>.
+ *  Returns the product of <i>self</i> and <i>other</i>.
+ *  When <i>other</i>'s class is Integer, it returns an OraNumber value.
+ *  Otherwise, it returns a value same with <i>other</i>'s class.
+ *
+ *  @example
+ *    OraNumber(2) * 3   # => #<OraNumber:6>
+ *    OraNumber(2) * 1.5 # => 3.0 (Float)
+ *
+ *  @param [Numeric] other
+ *  @return [Numeric]
  */
 static VALUE onum_mul(VALUE lhs, VALUE rhs)
 {
@@ -914,10 +1017,18 @@
 
 /*
  *  call-seq:
- *    onum / integer   -> oranumber
- *    onum / numeric   -> numeric
+ *    self / other
  *
- *  Returns the result of dividing <i>onum</i> by <i>other</i>.
+ *  Returns the result of dividing <i>self</i> by <i>other</i>.
+ *  When <i>other</i>'s class is Integer, it returns an OraNumber value.
+ *  Otherwise, it returns a value same with <i>other</i>'s class.
+ *
+ *  @example
+ *    OraNumber(2) / 3   # => #<OraNumber:0.6666666666666666666666666666666666666667>
+ *    OraNumber(2) / 1.5 # => 1.3333333333333333 (Float)
+ *
+ *  @param [Numeric] other
+ *  @return [Numeric]
  */
 static VALUE onum_div(VALUE lhs, VALUE rhs)
 {
@@ -956,9 +1067,17 @@
 
 /*
  *  call-seq:
- *    onum % other   -> oranumber
+ *    self % other
  *
- *  Returns the modulo after division of <i>onum</i> by <i>other</i>.
+ *  Returns the modulo after division of <i>self</i> by <i>other</i>.
+ *
+ *  @example
+ *    OraNumber(13) % 5 # => #<OraNumber:3>
+ *
+ *  @param [Numeric] other
+ *  @return [OraNumber]
+ *
+ *  @raise [ZeroDivisionError] when <i>other</i> is zero.
  */
 static VALUE onum_mod(VALUE lhs, VALUE rhs)
 {
@@ -981,9 +1100,16 @@
 
 /*
  *  call-seq:
- *    onum ** other   -> oranumber
+ *    self ** other
  *
- *  Raises <i>onum</i> the <i>other</i> power.
+ *  Raises <i>self</i> to the power of <i>other</i>.
+ *
+ *  @example
+ *    OraNumber(2) ** 2   # => #<OraNumber:4>
+ *    OraNumber(2) ** 2.5 # => #<OraNumber:5.65685424949238019520675489683879231435>
+ *
+ *  @param [Numeric] other
+ *  @return [OraNumber]
  */
 static VALUE onum_power(VALUE lhs, VALUE rhs)
 {
@@ -1004,11 +1130,19 @@
 
 /*
  *  call-seq:
- *    onum <=> other   -> -1, 0, +1
+ *    self <=> other
  *
- *  Returns -1, 0, or +1 depending on whether <i>onum</i> is less than,
+ *  Returns -1, 0, or +1 depending on whether <i>self</i> is less than,
  *  equal to, or greater than <i>other</i>. This is the basis for the
  *  tests in <code>Comparable</code>.
+ *
+ *  @example
+ *    OraNumber(5) <=> 3   # => 1
+ *    OraNumber(4) <=> 4   # => 0
+ *    OraNumber(2) <=> 2.5 # => 1
+ *
+ *  @param [Numeric] other
+ *  @return [-1, 0 or +1]
  */
 static VALUE onum_cmp(VALUE lhs, VALUE rhs)
 {
@@ -1031,10 +1165,14 @@
 }
 
 /*
- *  call-seq:
- *     onum.floor   -> integer
+ *  Returns the largest <code>Integer</code> less than or equal to <i>self</i>.
  *
- *  Returns the largest <code>Integer</code> less than or equal to <i>onum</i>.
+ *  @example
+ *    OraNumber(11.1).floor  # => 11
+ *    OraNumber(25.8).floor  # => 25
+ *    OraNumber(-25.8).floor # => -26
+ *
+ *  @return [Integer]
  */
 static VALUE onum_floor(VALUE self)
 {
@@ -1046,11 +1184,14 @@
 }
 
 /*
- *  call-seq:
- *     onum.ceil    -> integer
+ *  Returns the smallest <code>Integer</code> greater than or equal to <i>self</i>.
  *
- *  Returns the smallest <code>Integer</code> greater than or equal to
- *  <i>onum</i>.
+ *  @example
+ *    OraNumber(11.1).ceil  # => 12
+ *    OraNumber(25.8).ceil  # => 26
+ *    OraNumber(-25.8).ceil # => -25
+ *
+ *  @return [Integer]
  */
 static VALUE onum_ceil(VALUE self)
 {
@@ -1062,16 +1203,30 @@
 }
 
 /*
- *  call-seq:
- *     onum.round      -> integer
- *     onum.round(decplace) -> oranumber
+ *  @overload round
  *
- *  Rounds <i>onum</i> to the nearest <code>Integer</code> when no argument.
- *  Rounds <i>onum</i> to a specified decimal place <i>decplace</i> when one argument.
+ *    Rounds <i>self</i> to the nearest <code>Integer</code>.
  *
- *   OraNumber.new(1.234).round(1)  #=> 1.2
- *   OraNumber.new(1.234).round(2)  #=> 1.23
- *   OraNumber.new(1.234).round(3)  #=> 1.234
+ *    @example
+ *      OraNumber(1.49).round     # => 1
+ *      OraNumber(1.5).round      # => 2
+ *      OraNumber(-1.49).round    # => -1
+ *      OraNumber(-1.5).round     # => -2
+ *
+ *    @return [Integer]
+ *
+ *  @overload round(decplace)
+ *
+ *    Rounds <i>onum</i> to a specified decimal place <i>decplace</i>.
+ *
+ *    @example
+ *      OraNumber(123.456).round(2)   # => #<OraNumber:123.46>
+ *      OraNumber(123.456).round(1)   # => #<OraNumber:123.5>
+ *      OraNumber(123.456).round(0)   # => #<OraNumber:123>
+ *      OraNumber(123.456).round(-1)  # => #<OraNumber:120>
+ *
+ *    @param [Integer]
+ *    @return [OraNumber]
  */
 static VALUE onum_round(int argc, VALUE *argv, VALUE self)
 {
@@ -1090,11 +1245,24 @@
 
 /*
  *  call-seq:
- *     onum.truncate     -> integer
- *     onum.truncate(decplace) -> oranumber
+ *    truncate(decplace = 0)
  *
- *  Truncates <i>onum</i> to the <code>Integer</code> when no argument.
- *  Truncates <i>onum</i> to a specified decimal place <i>decplace</i> when one argument.
+ *  Truncates <i>self</i> to a specified decimal place <i>decplace</i>.
+ *
+ *  @example
+ *    OraNumber(123.456).truncate      # => #<OraNumber:123>
+ *    OraNumber(123.456).truncate(1)   # => #<OraNumber:123.4>
+ *    OraNumber(123.456).truncate(2)   # => #<OraNumber:123.45>
+ *    OraNumber(123.456).truncate(-1)  # => #<OraNumber:120>
+ *    
+ *    OraNumber(-123.456).truncate     # => #<OraNumber:-123>
+ *    OraNumber(-123.456).truncate(1)  # => #<OraNumber:-123.4>
+ *    OraNumber(-123.456).truncate(2)  # => #<OraNumber:-123.45>
+ *    OraNumber(-123.456).truncate(-1) # => #<OraNumber:-120>
+ *
+ *  @param [Integer]
+ *  @return [OraNumber]
+ *  @todo returns {Integer} when <i>decplace</i> is not specified.
  */
 static VALUE onum_trunc(int argc, VALUE *argv, VALUE self)
 {
@@ -1109,14 +1277,17 @@
 
 /*
  *  call-seq:
- *     onum.round_prec(digits) -> oranumber
+ *     round_prec(digits)
  *
- *  Rounds <i>onum</i> to a specified number of decimal digits.
+ *  Rounds <i>self</i> to a specified number of decimal digits.
  *  This method is available on Oracle 8.1 client or upper.
  *
- *   OraNumber.new(1.234).round_prec(2)  #=> 1.2
- *   OraNumber.new(12.34).round_prec(2)  #=> 12
- *   OraNumber.new(123.4).round_prec(2)  #=> 120
+ *  @example
+ *    OraNumber(1.234).round_prec(2) # => #<OraNumber:1.2>
+ *    OraNumber(12.34).round_prec(2) # => #<OraNumber:12>
+ *    OraNumber(123.4).round_prec(2) # => #<OraNumber:120>
+ *
+ *  @return [OraNumber]
  */
 static VALUE onum_round_prec(VALUE self, VALUE ndigs)
 {
@@ -1129,11 +1300,20 @@
 
 /*
  *  call-seq:
- *     onum.to_char(fmt = nil, nls_params = nil)  -> string
+ *     onum.to_char(fmt = nil, nlsparam = nil)
  *
  *  Returns a string containing a representation of self.
- *  <i>fmt</i> and <i>nls_params</i> are same meanings with
- *  <code>TO_CHAR</code> of Oracle function.
+ *  <i>fmt</i> and <i>nlsparam</i> are used as 
+ *  {http://docs.oracle.com/cd/E11882_01/server.112/e17118/functions201.htm Oracle SQL function TO_CHAR(number)}
+ *  does.
+ *
+ *  @example
+ *    OraNumber(123456.789).to_char('FM999,999,999.999')  # => "123,456.789"
+ *    OraNumber(123456.789).to_char('FM999G999G999D999',  "NLS_NUMERIC_CHARACTERS = ',.'") # => "123.456,789"
+ *
+ *  @param [String] fmt
+ *  @param [String] nlsparam
+ *  @return [String]
  */
 static VALUE onum_to_char(int argc, VALUE *argv, VALUE self)
 {
@@ -1185,10 +1365,11 @@
 }
 
 /*
- *  call-seq:
- *     onum.to_s    -> string
+ *  Returns a string containing a representation of self.
  *
- *  Returns a string containing a representation of self.
+ *  @return [String]
+ *
+ *  @see #to_char
  */
 static VALUE onum_to_s(VALUE self)
 {
@@ -1196,10 +1377,9 @@
 }
 
 /*
- *  call-seq:
- *     onum.to_i       -> integer
+ *  Returns <i>self</i> truncated to an <code>Integer</code>.
  *
- *  Returns <i>onum</i> truncated to an <code>Integer</code>.
+ *  @return [Integer]
  */
 static VALUE onum_to_i(VALUE self)
 {
@@ -1211,11 +1391,14 @@
 }
 
 /*
- *  call-seq:
- *     onum.to_f -> float
+ *  Converts <i>self</i> to <code>Float</code>.
  *
- *  Return the value as a <code>Float</code>.
+ *  When {OCI8.properties OCI8.properties [:float_conversion_type\]}
+ *  is <code>:ruby</code>, <i>self</I> is converted by <code>self.to_s.to_f</code>.
+ *  When it is <code>:oracle</code>, <i>self</I> is converted by the Oracle
+ *  OCI function OCINumberToReal().
  *
+ *  @return [Float]
  */
 static VALUE onum_to_f(VALUE self)
 {
@@ -1223,11 +1406,9 @@
 }
 
 /*
- *  call-seq:
- *     onum.to_r -> rational
+ *  Returns <i>self</i> as a <code>Rational</code>.
  *
- *  Return the value as a <code>Rational</code>.
- *
+ *  @return [Rational]
  */
 static VALUE onum_to_r(VALUE self)
 {
@@ -1266,11 +1447,9 @@
 }
 
 /*
- *  call-seq:
- *     onum.to_d -> bigdecimal
+ *  Returns <i>self</i> as a <code>BigDecimal</code>.
  *
- *  Return the value as a <code>BigDecimal</code>.
- *
+ *  @return [BigDecimal]
  */
 static VALUE onum_to_d(VALUE self)
 {
@@ -1294,13 +1473,14 @@
 }
 
 /*
- *  call-seq:
- *     onum.has_decimal_part? -> true or false
+ *  Returns <code>true</code> if <i>self</i> has a decimal part.
  *
- *  Returns +true+ if <i>self</i> has a decimal part.
- *
+ *  @example
  *    OraNumber(10).has_decimal_part?   # => false
  *    OraNumber(10.1).has_decimal_part? # => true
+ *
+ *  @return [true or false]
+ *  @since 2.0.5
  */
 static VALUE onum_has_decimal_part_p(VALUE self)
 {
@@ -1312,11 +1492,9 @@
 }
 
 /*
- *  call-seq:
- *     onum.to_onum -> oranumber
- *
  *  Returns self.
  *
+ *  @return [OraNumber]
  */
 static VALUE onum_to_onum(VALUE self)
 {
@@ -1324,11 +1502,9 @@
 }
 
 /*
- *  call-seq:
- *     onum.zero?    -> true or false
+ *  Returns <code>true</code> if <i>self</i> is zero.
  *
- *  Returns <code>true</code> if <i>onum</i> is zero.
- *
+ *  @return [true or false]
  */
 static VALUE onum_zero_p(VALUE self)
 {
@@ -1340,11 +1516,9 @@
 }
 
 /*
- *  call-seq:
- *     onum.abs -> oranumber
+ *  Returns the absolute value of <i>self</i>.
  *
- *  Returns the absolute value of <i>onum</i>.
- *
+ *  @return [OraNumber]
  */
 static VALUE onum_abs(VALUE self)
 {
@@ -1357,10 +1531,16 @@
 
 /*
  *  call-seq:
- *     onum.shift(fixnum)    -> oranumber
+ *     shift(ndigits)
  *
- *  Returns <i>onum</i> * 10**<i>fixnum</i>
+ *  Returns <i>self</i> shifted by <i>ndigits</i>
  *  This method is available on Oracle 8.1 client or upper.
+ *
+ *  @example
+ *     OraNumber(123).shift(3)  # => #<OraNumber:123000>
+ *     OraNumber(123).shift(-3) # => #<OraNumber:0.123>
+ *
+ *  @return [OraNumber]
  */
 static VALUE onum_shift(VALUE self, VALUE exp)
 {
@@ -1372,15 +1552,16 @@
 }
 
 /*
- *  call-seq:
- *     onum.dump    -> string
+ *  Returns internal representation whose format is same with the return value of
+ *  {http://docs.oracle.com/cd/E11882_01/server.112/e17118/functions055.htm Oracle SQL function DUMP}.
  *
- *  Returns internal representation whose format is same with
- *  the return value of Oracle SQL function DUMP().
+ *  @example
+ *    OraNumber.new(100).dump  #=> "Typ=2 Len=2: 194,2"
+ *    OraNumber.new(123).dump  #=> "Typ=2 Len=3: 194,2,24"
+ *    OraNumber.new(0.1).dump  #=> "Typ=2 Len=2: 192,11"
  *
- *   OraNumber.new(100).dump  #=> "Typ=2 Len=2: 194,2"
- *   OraNumber.new(123).dump  #=> "Typ=2 Len=3: 194,2,24"
- *   OraNumber.new(0.1).dump  #=> "Typ=2 Len=2: 192,11"
+ *  @return [String]
+ *  @since 2.0.4
  */
 static VALUE onum_dump(VALUE self)
 {
@@ -1389,6 +1570,9 @@
     return rb_usascii_str_new(buf, rv);
 }
 
+/*
+ *  @private
+ */
 static VALUE onum_hash(VALUE self)
 {
     char *c  = DATA_PTR(self);
@@ -1406,6 +1590,9 @@
     return INT2FIX(hash);
 }
 
+/*
+ *  @private
+ */
 static VALUE onum_inspect(VALUE self)
 {
     const char *name = rb_class2name(CLASS_OF(self));
@@ -1420,9 +1607,13 @@
 
 /*
  *  call-seq:
- *    onum._dump   -> string
+ *    _dump
  *
- *  Dump <i>onum</i> for marshaling.
+ *  Serializes <i>self</i>.
+ *  This method is called by Marshal.dump().
+ *
+ *  @return [String] a byte stream
+ *  @see OraNumber._load
  */
 static VALUE onum__dump(int argc, VALUE *argv, VALUE self)
 {
@@ -1436,9 +1627,14 @@
 
 /*
  *  call-seq:
- *    OraNumber._load(string)   -> oranumber
+ *    _load(bytes)
  *
- *  Unmarshal a dumped <code>OraNumber</code> object.
+ *  Restores a byte stream serialized by {OraNumber#_dump}.
+ *  This method is called by Marshal.load() to deserialize a byte stream
+ *  created by Marshal.dump().
+ *
+ *  @param [String] bytes a byte stream
+ *  @return [OraNumber] an deserialized object
  */
 static VALUE
 onum_s_load(VALUE klass, VALUE str)
@@ -1459,8 +1655,17 @@
 }
 
 /*
- * bind_ocinumber
+ *  Document-class: OCI8::BindType::OraNumber
  */
+
+/*
+ *  Document-class: OCI8::BindType::Integer
+ */
+
+/*
+ *  Document-class: OCI8::BindType::Float
+ */
+
 static VALUE bind_ocinumber_get(oci8_bind_t *obind, void *data, void *null_struct)
 {
     return oci8_make_ocinumber((OCINumber*)data, oci8_errhp);
@@ -1591,13 +1796,6 @@
     OCINumberSetPi(errhp, &num1);
     obj_PI = oci8_make_ocinumber(&num1, errhp);
 
-    /* Document-module: OCI8::Math
-     *
-     *  The <code>OCI8::Math</code> module contains module functions for basic
-     *  trigonometric and transcendental functions. Their accuracy is
-     *  same with {OraNumber}.
-     */
-
     /* The ratio of the circumference of a circle to its diameter. */
     rb_define_const(mMath, "PI", obj_PI);
 

Modified: trunk/ruby-oci8/lib/oci8/oci8.rb
===================================================================
--- trunk/ruby-oci8/lib/oci8/oci8.rb	2012-04-03 11:08:37 UTC (rev 499)
+++ trunk/ruby-oci8/lib/oci8/oci8.rb	2012-04-05 13:36:06 UTC (rev 500)
@@ -1,6 +1,6 @@
 # oci8.rb -- implements OCI8 and OCI8::Cursor
 #
-# Copyright (C) 2002-2010 KUBO Takehiro <kubo at jiubao.org>
+# Copyright (C) 2002-2012 KUBO Takehiro <kubo at jiubao.org>
 #
 # Original Copyright is:
 #   Oracle module for Ruby
@@ -733,39 +733,60 @@
   if defined? Psych and YAML == Psych
 
     yaml_tag '!ruby/object:OraNumber'
-    def encode_with coder # :nodoc:
+
+    # @private
+    def encode_with coder
       coder.scalar = self.to_s
     end
 
-    def init_with coder # :nodoc:
+    # @private
+    def init_with coder
       initialize(coder.scalar)
     end
 
   else
 
-    def yaml_initialize(type, val) # :nodoc:
+    # @private
+    def yaml_initialize(type, val)
       initialize(val)
     end
 
-    def to_yaml(opts = {}) # :nodoc:
+    # @private
+    def to_yaml(opts = {})
       YAML.quick_emit(object_id, opts) do |out|
         out.scalar(taguri, self.to_s, :plain)
       end
     end
   end
 
-  def to_json(options=nil) # :nodoc:
+  # @private
+  def to_json(options=nil)
     to_s
   end
 end
 
 class Numeric
+  # Converts +self+ to {OraNumber}.
   def to_onum
     OraNumber.new(self)
   end
 end
 
-class String
+class String # :nodoc:
+
+  # Converts +self+ to {OraNumber}.
+  # Optional <i>fmt</i> and <i>nlsparam</i> is used as
+  # {http://docs.oracle.com/cd/E11882_01/server.112/e17118/functions211.htm Oracle SQL function TO_NUMBER}
+  # does.
+  #
+  # @example
+  #   '123456.789'.to_onum # => #<OraNumber:123456.789>
+  #   '123,456.789'.to_onum('999,999,999.999') # => #<OraNumber:123456.789>
+  #   '123.456,789'.to_onum('999G999G999D999', "NLS_NUMERIC_CHARACTERS = ',.'") # => #<OraNumber:123456.789>
+  #
+  # @param [String] fmt
+  # @param [String] nlsparam
+  # @return [OraNumber]
   def to_onum(format = nil, nls_params = nil)
     OraNumber.new(self, format, nls_params)
   end


From nobody at rubyforge.org  Fri Apr  6 12:26:57 2012
From: nobody at rubyforge.org (nobody at rubyforge.org)
Date: Fri,  6 Apr 2012 12:26:57 +0000 (UTC)
Subject: [ruby-oci8-commit] [501] trunk/ruby-oci8: revise rdoc comments.
Message-ID: <20120406122658.089774A80F@rubyforge.org>

Revision: 501
Author:   kubo
Date:     2012-04-06 12:26:57 +0000 (Fri, 06 Apr 2012)
Log Message:
-----------
revise rdoc comments.

Modified Paths:
--------------
    trunk/ruby-oci8/ChangeLog
    trunk/ruby-oci8/ext/oci8/error.c
    trunk/ruby-oci8/ext/oci8/ocihandle.c
    trunk/ruby-oci8/ext/oci8/oradate.c
    trunk/ruby-oci8/lib/oci8/encoding-init.rb
    trunk/ruby-oci8/lib/oci8/oci8.rb
    trunk/ruby-oci8/lib/oci8/ocihandle.rb

Modified: trunk/ruby-oci8/ChangeLog
===================================================================
--- trunk/ruby-oci8/ChangeLog	2012-04-05 13:36:06 UTC (rev 500)
+++ trunk/ruby-oci8/ChangeLog	2012-04-06 12:26:57 UTC (rev 501)
@@ -1,3 +1,8 @@
+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:
+	    revise rdoc comments.
+
 2012-04-05  KUBO Takehiro  <kubo at jiubao.org>
 	* ext/oci8/ocinumber.c, lib/oci8/oci8.rb: revise OraNumber's comments.
 

Modified: trunk/ruby-oci8/ext/oci8/error.c
===================================================================
--- trunk/ruby-oci8/ext/oci8/error.c	2012-04-05 13:36:06 UTC (rev 500)
+++ trunk/ruby-oci8/ext/oci8/error.c	2012-04-06 12:26:57 UTC (rev 501)
@@ -2,7 +2,7 @@
 /*
   error.c - part of ruby-oci8
 
-  Copyright (C) 2002-2011 KUBO Takehiro <kubo at jiubao.org>
+  Copyright (C) 2002-2012 KUBO Takehiro <kubo at jiubao.org>
 
 */
 #include "oci8.h"
@@ -162,9 +162,13 @@
 
 /*
  * call-seq:
- *    OCI8.new(message, code = nil, sql = nil, parse_error_offset = nil)
+ *    initialize(message, code = nil, sql = nil, parse_error_offset = nil)
  *
  * Creates a new OCIError object.
+ *
+ * @example
+ *   OCIError.new("ORA-00001: unique constraint (%s.%s) violated", 1)
+ *   # => #<OCIError: ORA-00001: unique constraint (%s.%s) violated>
  */
 static VALUE oci8_error_initialize(int argc, VALUE *argv, VALUE self)
 {
@@ -211,6 +215,10 @@
     eOCISuccessWithInfo = rb_define_class("OCISuccessWithInfo", eOCIError);
 
     rb_define_method(eOCIError, "initialize", oci8_error_initialize, -1);
+
+    /*
+     * @attr_reader [Integer] code  error code
+     */
     rb_define_attr(eOCIError, "code", 1, 0);
     rb_define_attr(eOCIError, "sql", 1, 0);
     rb_define_attr(eOCIError, "parse_error_offset", 1, 0);
@@ -296,14 +304,11 @@
  * These exceptions are raised when Oracle Call Interface functions
  * return with an error status.
  *
- * - OCIBreak
- * - OCIContinue
- * - OCIError
- *   - OCISuccessWithInfo
- *   - OCINoData (It had been a subclass of OCIException, not OCIError, until ruby-oci8 2.0)
- * - OCIInvalidHandle
- * - OCINeedData
- * - OCIStillExecuting
+ * - {OCIBreak}
+ * - {OCIError}
+ *   - {OCISuccessWithInfo}
+ *   - {OCINoData} (It had been a subclass of OCIException, not OCIError, until ruby-oci8 2.0)
+ * - {OCIInvalidHandle}
  */
 
 /*
@@ -311,7 +316,7 @@
  *
  * Subclass of OCIException
  *
- * Raised when a SQL execution is cancelled by OCI8#break.
+ * Raised when a SQL execution is cancelled by {OCI8#break}.
  */
 
 /*
@@ -335,6 +340,10 @@
  *
  * Raised when underlying Oracle Call Interface failed with an Oracle error code
  * such as ORA-00001.
+ *
+ * @attr_reader [Integer] code  error code
+ * @attr_reader [String] sql    SQL statement
+ * @attr_reader [Integer] parse_error_offset position
  */
 
 /*
@@ -352,6 +361,8 @@
  * Subclass of OCIException
  *
  * Report to the ruby-oci8 author if it is raised.
+ *
+ * @private
  */
 
 /*
@@ -360,6 +371,8 @@
  * Subclass of OCIError
  *
  * Report to the ruby-oci8 author if it is raised.
+ *
+ * @private
  */
 
 /*
@@ -368,6 +381,8 @@
  * Subclass of OCIException
  *
  * Report to the ruby-oci8 author if it is raised.
+ *
+ * @private
  */
 
 /*

Modified: trunk/ruby-oci8/ext/oci8/ocihandle.c
===================================================================
--- trunk/ruby-oci8/ext/oci8/ocihandle.c	2012-04-05 13:36:06 UTC (rev 500)
+++ trunk/ruby-oci8/ext/oci8/ocihandle.c	2012-04-06 12:26:57 UTC (rev 501)
@@ -2,7 +2,7 @@
 /*
  * ocihandle.c
  *
- * Copyright (C) 2009-2010 KUBO Takehiro <kubo at jiubao.org>
+ * Copyright (C) 2009-2012 KUBO Takehiro <kubo at jiubao.org>
  *
  * implement OCIHandle
  *
@@ -38,12 +38,10 @@
 }
 
 /*
- * call-seq:
- *   free()
+ * Clears the object internal structure and its dependents.
  *
- * <b>(new in 2.0.0)</b>
- *
- * Clears the object internal structure and its dependents.
+ * @since 2.0.0
+ * @private
  */
 static VALUE oci8_handle_free(VALUE self)
 {
@@ -107,11 +105,15 @@
 
 /*
  * call-seq:
- *   attr_get_ub1(attr_type) -> fixnum
+ *   attr_get_ub1(attr_type)
  *
- * <b>(new in 2.0.4)</b>
+ * Gets the value of an attribute as `ub1' datatype.
  *
- * Gets the value of an attribute as `ub1' datatype.
+ * @param [Fixnum] attr_type
+ * @return [Fixnum]
+ *
+ * @since 2.0.4
+ * @private
  */
 static VALUE attr_get_ub1(VALUE self, VALUE attr_type)
 {
@@ -129,11 +131,15 @@
 
 /*
  * call-seq:
- *   attr_get_ub2(attr_type) -> fixnum
+ *   attr_get_ub2(attr_type)
  *
- * <b>(new in 2.0.4)</b>
+ * Gets the value of an attribute as `ub2' datatype.
  *
- * Gets the value of an attribute as `ub2' datatype.
+ * @param [Fixnum] attr_type
+ * @return [Fixnum]
+ *
+ * @since 2.0.4
+ * @private
  */
 static VALUE attr_get_ub2(VALUE self, VALUE attr_type)
 {
@@ -151,11 +157,15 @@
 
 /*
  * call-seq:
- *   attr_get_ub4(attr_type) -> integer
+ *   attr_get_ub4(attr_type)
  *
- * <b>(new in 2.0.4)</b>
+ * Gets the value of an attribute as `ub4' datatype.
  *
- * Gets the value of an attribute as `ub4' datatype.
+ * @param [Fixnum] attr_type
+ * @return [Integer]
+ *
+ * @since 2.0.4
+ * @private
  */
 static VALUE attr_get_ub4(VALUE self, VALUE attr_type)
 {
@@ -173,11 +183,15 @@
 
 /*
  * call-seq:
- *   attr_get_ub8(attr_type) -> integer
+ *   attr_get_ub8(attr_type)
  *
- * <b>(new in 2.0.4)</b>
+ * Gets the value of an attribute as `ub8' datatype.
  *
- * Gets the value of an attribute as `ub8' datatype.
+ * @param [Fixnum] attr_type
+ * @return [Integer]
+ *
+ * @since 2.0.4
+ * @private
  */
 static VALUE attr_get_ub8(VALUE self, VALUE attr_type)
 {
@@ -195,11 +209,15 @@
 
 /*
  * call-seq:
- *   attr_get_sb1(attr_type) -> fixnum
+ *   attr_get_sb1(attr_type)
  *
- * <b>(new in 2.0.4)</b>
+ * Gets the value of an attribute as `sb1' datatype.
  *
- * Gets the value of an attribute as `sb1' datatype.
+ * @param [Fixnum] attr_type
+ * @return [Fixnum]
+ *
+ * @since 2.0.4
+ * @private
  */
 static VALUE attr_get_sb1(VALUE self, VALUE attr_type)
 {
@@ -217,11 +235,15 @@
 
 /*
  * call-seq:
- *   attr_get_sb2(attr_type) -> fixnum
+ *   attr_get_sb2(attr_type)
  *
- * <b>(new in 2.0.4)</b>
+ * Gets the value of an attribute as `sb2' datatype.
  *
- * Gets the value of an attribute as `sb2' datatype.
+ * @param [Fixnum] attr_type
+ * @return [Fixnum]
+ *
+ * @since 2.0.4
+ * @private
  */
 static VALUE attr_get_sb2(VALUE self, VALUE attr_type)
 {
@@ -239,11 +261,15 @@
 
 /*
  * call-seq:
- *   attr_get_sb4(attr_type) -> integer
+ *   attr_get_sb4(attr_type)
  *
- * <b>(new in 2.0.4)</b>
+ * Gets the value of an attribute as `sb4' datatype.
  *
- * Gets the value of an attribute as `sb4' datatype.
+ * @param [Fixnum] attr_type
+ * @return [Integer]
+ *
+ * @since 2.0.4
+ * @private
  */
 static VALUE attr_get_sb4(VALUE self, VALUE attr_type)
 {
@@ -261,11 +287,15 @@
 
 /*
  * call-seq:
- *   attr_get_sb8(attr_type) -> integer
+ *   attr_get_sb8(attr_type)
  *
- * <b>(new in 2.0.4)</b>
+ * Gets the value of an attribute as `sb8' datatype.
  *
- * Gets the value of an attribute as `sb8' datatype.
+ * @param [Fixnum] attr_type
+ * @return [Integer]
+ *
+ * @since 2.0.4
+ * @private
  */
 static VALUE attr_get_sb8(VALUE self, VALUE attr_type)
 {
@@ -283,11 +313,15 @@
 
 /*
  * call-seq:
- *   attr_get_boolean(attr_type) -> true or false
+ *   attr_get_boolean(attr_type)
  *
- * <b>(new in 2.0.4)</b>
+ * Gets the value of an attribute as `boolean' datatype.
  *
- * Gets the value of an attribute as `boolean' datatype.
+ * @param [Fixnum] attr_type
+ * @return [true of false]
+ *
+ * @since 2.0.4
+ * @private
  */
 static VALUE attr_get_boolean(VALUE self, VALUE attr_type)
 {
@@ -305,16 +339,20 @@
 
 /*
  * call-seq:
- *   attr_get_string(attr_type) -> string
+ *   attr_get_string(attr_type)
  *
- * <b>(new in 2.0.4)</b>
- *
  * Gets the value of an attribute as `oratext *' datatype.
  * The return value is converted to Encoding.default_internal or
- * tagged with OCI8.encoding when the ruby version is 1.9.
+ * tagged with {OCI8.encoding} when the ruby version is 1.9.
  *
- * <b>Caution:</b> If the specified attr_type's datatype is not a
- * pointer type, it causes a segmentation fault.
+ * @note If the specified attr_type's datatype is not a
+ *   pointer type, it causes a segmentation fault.
+ *
+ * @param [Fixnum] attr_type
+ * @return [String]
+ *
+ * @since 2.0.4
+ * @private
  */
 static VALUE attr_get_string(VALUE self, VALUE attr_type)
 {
@@ -333,15 +371,19 @@
 
 /*
  * call-seq:
- *   attr_get_binary(attr_type) -> string
+ *   attr_get_binary(attr_type)
  *
- * <b>(new in 2.0.4)</b>
- *
  * Gets the value of an attribute as `ub1 *' datatype.
  * The return value is tagged with ASCII-8BIT when the ruby version is 1.9.
  *
- * <b>Caution:</b> If the specified attr_type's datatype is not a
- * pointer type, it causes a segmentation fault.
+ * @note If the specified attr_type's datatype is not a
+ *   pointer type, it causes a segmentation fault.
+ *
+ * @param [Fixnum] attr_type
+ * @return [String]
+ *
+ * @since 2.0.4
+ * @private
  */
 static VALUE attr_get_binary(VALUE self, VALUE attr_type)
 {
@@ -362,13 +404,17 @@
  * call-seq:
  *   attr_get_integer(attr_type) -> integer
  *
- * <b>(new in 2.0.4)</b>
- *
  * Gets the value of an attribute as `ub1 *' datatype.
  * The return value is converted to Integer from internal Oracle NUMBER format.
  *
- * <b>Caution:</b> If the specified attr_type's datatype is not a
- * pointer type, it causes a segmentation fault.
+ * @note If the specified attr_type's datatype is not a
+ *   pointer type, it causes a segmentation fault.
+ *
+ * @param [Fixnum] attr_type
+ * @return [Fixnum]
+ *
+ * @since 2.0.4
+ * @private
  */
 static VALUE attr_get_integer(VALUE self, VALUE attr_type)
 {
@@ -389,13 +435,17 @@
  * call-seq:
  *   attr_get_oradate(attr_type) -> an OraDate
  *
- * <b>(new in 2.1.0)</b>
- *
  * Gets the value of an attribute as `ub1 *' datatype.
  * The return value is converted to OraDate.
  *
- * <b>Caution:</b> If the specified attr_type's datatype is not a
- * pointer type, it causes a segmentation fault.
+ * @note If the specified attr_type's datatype is not a
+ *   pointer type, it causes a segmentation fault.
+ *
+ * @param [Fixnum] attr_type
+ * @return [OraDate]
+ *
+ * @since 2.0.4
+ * @private
  */
 static VALUE attr_get_oradate(VALUE self, VALUE attr_type)
 {
@@ -425,12 +475,17 @@
  * call-seq:
  *   attr_set_ub1(attr_type, attr_value)
  *
- * <b>(new in 2.0.4)</b>
- *
  * Sets the value of an attribute as `ub1' datatype.
  *
- * <b>Caution:</b> If the specified attr_type's datatype is a
- * pointer type, it causes a segmentation fault.
+ * @note If the specified attr_type's datatype is a
+ *   pointer type, it causes a segmentation fault.
+ *
+ * @param [Fixnum] attr_type
+ * @param [Fixnum] attr_value
+ * @return [self]
+ *
+ * @since 2.0.4
+ * @private
  */
 static VALUE attr_set_ub1(VALUE self, VALUE attr_type, VALUE val)
 {
@@ -449,12 +504,17 @@
  * call-seq:
  *   attr_set_ub2(attr_type, attr_value)
  *
- * <b>(new in 2.0.4)</b>
- *
  * Sets the value of an attribute as `ub2' datatype.
  *
- * <b>Caution:</b> If the specified attr_type's datatype is a
- * pointer type, it causes a segmentation fault.
+ * @note If the specified attr_type's datatype is a
+ *   pointer type, it causes a segmentation fault.
+ *
+ * @param [Fixnum] attr_type
+ * @param [Fixnum] attr_value
+ * @return [self]
+ *
+ * @since 2.0.4
+ * @private
  */
 static VALUE attr_set_ub2(VALUE self, VALUE attr_type, VALUE val)
 {
@@ -473,12 +533,17 @@
  * call-seq:
  *   attr_set_ub4(attr_type, attr_value)
  *
- * <b>(new in 2.0.4)</b>
- *
  * Sets the value of an attribute as `ub4' datatype.
  *
- * <b>Caution:</b> If the specified attr_type's datatype is a
- * pointer type, it causes a segmentation fault.
+ * @note If the specified attr_type's datatype is a
+ *   pointer type, it causes a segmentation fault.
+ *
+ * @param [Fixnum] attr_type
+ * @param [Integer] attr_value
+ * @return [self]
+ *
+ * @since 2.0.4
+ * @private
  */
 static VALUE attr_set_ub4(VALUE self, VALUE attr_type, VALUE val)
 {
@@ -497,12 +562,17 @@
  * call-seq:
  *   attr_set_ub8(attr_type, attr_value)
  *
- * <b>(new in 2.0.4)</b>
- *
  * Sets the value of an attribute as `ub8' datatype.
  *
- * <b>Caution:</b> If the specified attr_type's datatype is a
- * pointer type, it causes a segmentation fault.
+ * @note If the specified attr_type's datatype is a
+ *   pointer type, it causes a segmentation fault.
+ *
+ * @param [Fixnum] attr_type
+ * @param [Integer] attr_value
+ * @return [self]
+ *
+ * @since 2.0.4
+ * @private
  */
 static VALUE attr_set_ub8(VALUE self, VALUE attr_type, VALUE val)
 {
@@ -521,12 +591,17 @@
  * call-seq:
  *   attr_set_sb1(attr_type, attr_value)
  *
- * <b>(new in 2.0.4)</b>
- *
  * Sets the value of an attribute as `sb1' datatype.
  *
- * <b>Caution:</b> If the specified attr_type's datatype is a
- * pointer type, it causes a segmentation fault.
+ * @note If the specified attr_type's datatype is a
+ *   pointer type, it causes a segmentation fault.
+ *
+ * @param [Fixnum] attr_type
+ * @param [Fixnum] attr_value
+ * @return [self]
+ *
+ * @since 2.0.4
+ * @private
  */
 static VALUE attr_set_sb1(VALUE self, VALUE attr_type, VALUE val)
 {
@@ -545,12 +620,17 @@
  * call-seq:
  *   attr_set_sb2(attr_type, attr_value)
  *
- * <b>(new in 2.0.4)</b>
- *
  * Sets the value of an attribute as `sb2' datatype.
  *
- * <b>Caution:</b> If the specified attr_type's datatype is a
- * pointer type, it causes a segmentation fault.
+ * @note If the specified attr_type's datatype is a
+ *  pointer type, it causes a segmentation fault.
+ *
+ * @param [Fixnum] attr_type
+ * @param [Fixnum] attr_value
+ * @return [self]
+ *
+ * @since 2.0.4
+ * @private
  */
 static VALUE attr_set_sb2(VALUE self, VALUE attr_type, VALUE val)
 {
@@ -569,12 +649,17 @@
  * call-seq:
  *   attr_set_sb4(attr_type, attr_value)
  *
- * <b>(new in 2.0.4)</b>
- *
  * Sets the value of an attribute as `sb4' datatype.
  *
- * <b>Caution:</b> If the specified attr_type's datatype is a
- * pointer type, it causes a segmentation fault.
+ * @note If the specified attr_type's datatype is a
+ *   pointer type, it causes a segmentation fault.
+ *
+ * @param [Fixnum] attr_type
+ * @param [Integer] attr_value
+ * @return [self]
+ *
+ * @since 2.0.4
+ * @private
  */
 static VALUE attr_set_sb4(VALUE self, VALUE attr_type, VALUE val)
 {
@@ -593,12 +678,17 @@
  * call-seq:
  *   attr_set_sb8(attr_type, attr_value)
  *
- * <b>(new in 2.0.4)</b>
- *
  * Sets the value of an attribute as `sb8' datatype.
  *
- * <b>Caution:</b> If the specified attr_type's datatype is a
- * pointer type, it causes a segmentation fault.
+ * @note If the specified attr_type's datatype is a
+ *   pointer type, it causes a segmentation fault.
+ *
+ * @param [Fixnum] attr_type
+ * @param [Integer] attr_value
+ * @return [self]
+ *
+ * @since 2.0.4
+ * @private
  */
 static VALUE attr_set_sb8(VALUE self, VALUE attr_type, VALUE val)
 {
@@ -617,12 +707,17 @@
  * call-seq:
  *   attr_set_boolean(attr_type, attr_value)
  *
- * <b>(new in 2.0.4)</b>
- *
  * Sets the value of an attribute as `boolean' datatype.
  *
- * <b>Caution:</b> If the specified attr_type's datatype is a
- * pointer type, it causes a segmentation fault.
+ * @note If the specified attr_type's datatype is a
+ *   pointer type, it causes a segmentation fault.
+ *
+ * @param [Fixnum] attr_type
+ * @param [true or false] attr_value
+ * @return [self]
+ *
+ * @since 2.0.4
+ * @private
  */
 static VALUE attr_set_boolean(VALUE self, VALUE attr_type, VALUE val)
 {
@@ -639,13 +734,18 @@
 
 /*
  * call-seq:
- *   attr_set_string(attr_type, string_value)
+ *   attr_set_string(attr_type, attr_value)
  *
- * <b>(new in 2.0.4)</b>
- *
  * Sets the value of an attribute as `oratext *' datatype.
- * +string_value+ is converted to OCI8.encoding before it is set
+ * +attr_value+ is converted to {OCI8.encoding} before it is set
  * when the ruby version is 1.9.
+ *
+ * @param [Fixnum] attr_type
+ * @param [String] attr_value
+ * @return [self]
+ *
+ * @since 2.0.4
+ * @private
  */
 static VALUE attr_set_string(VALUE self, VALUE attr_type, VALUE val)
 {
@@ -661,11 +761,16 @@
 
 /*
  * call-seq:
- *   attr_set_binary(attr_type, string_value)
+ *   attr_set_binary(attr_type, attr_value)
  *
- * <b>(new in 2.0.4)</b>
+ * Sets the value of an attribute as `ub1 *' datatype.
  *
- * Sets the value of an attribute as `ub1 *' datatype.
+ * @param [Fixnum] attr_type
+ * @param [String] attr_value
+ * @return [self]
+ *
+ * @since 2.0.4
+ * @private
  */
 static VALUE attr_set_binary(VALUE self, VALUE attr_type, VALUE val)
 {
@@ -683,11 +788,16 @@
  * call-seq:
  *   attr_set_integer(attr_type, number)
  *
- * <b>(new in 2.0.4)</b>
- *
  * Sets the value of an attribute as `ub1 *' datatype.
  * +number+ is converted to internal Oracle NUMBER format before
  * it is set.
+ *
+ * @param [Fixnum] attr_type
+ * @param [Numeric] number
+ * @return [self]
+ *
+ * @since 2.0.4
+ * @private
  */
 static VALUE attr_set_integer(VALUE self, VALUE attr_type, VALUE val)
 {
@@ -707,11 +817,11 @@
     VALUE obj;
 
     /*
-     * <b>(new in 2.0.0)</b>
-     *
      * OCIHandle is the abstract base class of OCI handles and
      * OCI descriptors; opaque data types of Oracle Call Interface.
      * Don't use constants and methods defined in the class.
+     *
+     * @since 2.0.0
      */
     oci8_cOCIHandle = rb_define_class("OCIHandle", rb_cObject);
     rb_define_alloc_func(oci8_cOCIHandle, oci8_s_allocate);

Modified: trunk/ruby-oci8/ext/oci8/oradate.c
===================================================================
--- trunk/ruby-oci8/ext/oci8/oradate.c	2012-04-05 13:36:06 UTC (rev 500)
+++ trunk/ruby-oci8/ext/oci8/oradate.c	2012-04-06 12:26:57 UTC (rev 501)
@@ -2,7 +2,7 @@
 /*
  *  oradate.c
  *
- * Copyright (C) 2002-2008 KUBO Takehiro <kubo at jiubao.org>
+ * Copyright (C) 2002-2012 KUBO Takehiro <kubo at jiubao.org>
  *
  * date and time between 4712 B.C. and 9999 A.D.
  */
@@ -14,9 +14,8 @@
 /*
  * Document-class: OraDate
  *
- * ruby class compatible with Oracle <tt>DATE</tt> data type.
- * Date and time between 4712 B.C. and 9999 A.D.
- *
+ * OraDate is the ruby class compatible with Oracle <tt>DATE</tt> data type.
+ * The range is between 4712 B.C. and 9999 A.D.
  */
 struct ora_date {
     unsigned char century;
@@ -79,10 +78,15 @@
 }
 
 /*
- * call-seq:
- *   OraDate.new(year = 1, month = 1, day = 1, hour = 0, min = 0, sec = 0) -> oradate
+ *  call-seq:
+ *   initialize(year = 1, month = 1, day = 1, hour = 0, min = 0, sec = 0)
  *
- * Returns an <code>OraDate</code> object initialized to the specified date and time.
+ *  Returns an <code>OraDate</code> object initialized to the specified date and time.
+ *
+ *  @example
+ *    OraDate.new              # => 0001-01-01 00:00:00
+ *    OraDate.new(2012)        # => 2012-01-01 00:00:00
+ *    OraDate.new(2012, 3, 4)  # => 2012-03-04 00:00:00
  */
 static VALUE ora_date_initialize(int argc, VALUE *argv, VALUE self)
 {
@@ -138,7 +142,9 @@
     return Qnil;
 }
 
-/* :nodoc: */
+/*
+ *  @private
+ */
 static VALUE ora_date_initialize_copy(VALUE lhs, VALUE rhs)
 {
     ora_date_t *l, *r;
@@ -151,11 +157,10 @@
 }
 
 /*
- * call-seq:
- *   OraDate.now() -> oradate
+ *  Returns an <code>OraDate</code> object initialized to the
+ *  current local time.
  *
- * Returns an <code>OraDate</code> object initialized to the
- * current local time.
+ *  @return [OraDate]
  */
 static VALUE ora_date_s_now(int argc, VALUE *argv, VALUE klass)
 {
@@ -183,11 +188,10 @@
 }
 
 /*
- * call-seq:
- *   oradate.to_s -> string
+ *  Returns a string representing <i>self</i>.
+ *  The string format is 'yyyy/mm/dd hh:mi:ss'.
  *
- * Returns a string representing <i>oradate</i>.
- * The string format is 'yyyy/mm/dd hh:mi:ss'.
+ *  @return [OraDate]
  */
 static VALUE ora_date_to_s(VALUE self)
 {
@@ -201,11 +205,9 @@
 }
 
 /*
- * call-seq:
- *   oradate.to_a -> array
+ *  Returns a 6-element <i>array</i> of year, month, day, hour, minute and second.
  *
- * Returns a 6-element <i>array</i> of values for <i>oradate</i>:
- * {<code>[year, month, day, hour, minute, second]</code>}.
+ *  @return [Array]
  */
 static VALUE ora_date_to_a(VALUE self)
 {
@@ -223,10 +225,9 @@
 }
 
 /*
- * call-seq:
- *   oradate.year -> fixnum
+ *  Returns the year field of <i>self</i>.
  *
- * Returns the year (-4712..9999) for <i>oradate</i>.
+ *  @return [Fixnum]
  */
 static VALUE ora_date_year(VALUE self)
 {
@@ -237,10 +238,12 @@
 }
 
 /*
- * call-seq:
- *   oradate.year = fixnum
+ *  call-seq:
+ *    year = num
  *
- * Sets the year (-4712..9999) for <i>oradate</i>.
+ *  Assigns <i>num</i> to the year field of <i>self</i>.
+ *
+ *  @param [Fixnum] number between -4712 and 9999
  */
 static VALUE ora_date_set_year(VALUE self, VALUE val)
 {
@@ -255,10 +258,10 @@
 }
 
 /*
- * call-seq:
- *   oradate.month -> fixnum
+ *  Returns the month field of <i>self</i>.
+ *  The month starts with one.
  *
- * Returns the month of the year (1..12) for <i>oradate</i>.
+ *  @return [Fixnum]
  */
 static VALUE ora_date_month(VALUE self)
 {
@@ -269,10 +272,13 @@
 }
 
 /*
- * call-seq:
- *   oradate.month = fixnum
+ *  call-seq:
+ *    month = num
  *
- * Sets the month of the year (1..12) for <i>oradate</i>.
+ *  Assigns <i>num</i> to the month field of <i>self</i>.
+ *  The month starts with one.
+ *
+ *  @param [Fixnum] number between 1 and 12
  */
 static VALUE ora_date_set_month(VALUE self, VALUE val)
 {
@@ -287,10 +293,9 @@
 }
 
 /*
- * call-seq:
- *   oradate.day -> fixnum
+ *  Returns the day of month field of <i>self</i>.
  *
- * Returns the day of the month (1..31) for <i>oradate</i>.
+ *  @return [Fixnum]
  */
 static VALUE ora_date_day(VALUE self)
 {
@@ -301,10 +306,12 @@
 }
 
 /*
- * call-seq:
- *   oradate.day = fixnum
+ *  call-seq:
+ *    day = num
  *
- * Sets the day of the month (1..31) for <i>oradate</i>.
+ *  Assigns <i>num</i> to the day of month field of <i>self</i>.
+ *
+ *  @param [Fixnum] number between 1 and 31
  */
 static VALUE ora_date_set_day(VALUE self, VALUE val)
 {
@@ -319,10 +326,9 @@
 }
 
 /*
- * call-seq:
- *   oradate.hour -> fixnum
+ *  Returns the hour field of <i>self</i>.
  *
- * Returns the hour of the day (0..23) for <i>oradate</i>.
+ *  @return [Fixnum]
  */
 static VALUE ora_date_hour(VALUE self)
 {
@@ -333,10 +339,12 @@
 }
 
 /*
- * call-seq:
- *   oradate.hour = fixnum
+ *  call-seq:
+ *    hour = num
  *
- * Sets the hour of the day (0..23) for <i>oradate</i>.
+ *  Assigns <i>num</i> to the hour field of <i>self</i>.
+ *
+ *  @param [Fixnum] number between 0 and 23
  */
 static VALUE ora_date_set_hour(VALUE self, VALUE val)
 {
@@ -351,10 +359,9 @@
 }
 
 /*
- * call-seq:
- *   oradate.minute -> fixnum
+ *  Returns the minute field of <i>self</i>.
  *
- * Returns the minute of the hour (0..59) for <i>oradate</i>.
+ *  @return [Fixnum]
  */
 static VALUE ora_date_minute(VALUE self)
 {
@@ -365,10 +372,12 @@
 }
 
 /*
- * call-seq:
- *   oradate.minute = fixnum
+ *  call-seq:
+ *    minute = num
  *
- * Sets the minute of the hour (0..59) for <i>oradate</i>.
+ *  Assigns <i>num</i> to the minute field of <i>self</i>.
+ *
+ *  @param [Fixnum] number between 0 and 59
  */
 static VALUE ora_date_set_minute(VALUE self, VALUE val)
 {
@@ -383,10 +392,9 @@
 }
 
 /*
- * call-seq:
- *   oradate.second -> fixnum
+ *  Returns the second field of <i>self</i>.
  *
- * Returns the second of the minute (0..59) for <i>oradate</i>.
+ *  @return [Fixnum]
  */
 static VALUE ora_date_second(VALUE self)
 {
@@ -397,10 +405,12 @@
 }
 
 /*
- * call-seq:
- *   oradate.second = fixnum
+ *  call-seq:
+ *    second = num
  *
- * Sets the second of the minute (0..59) for <i>oradate</i>.
+ *  Assigns <i>num</i> to the second field of <i>self</i>.
+ *
+ *  @param [Fixnum] number between 0 and 59
  */
 static VALUE ora_date_set_second(VALUE self, VALUE val)
 {
@@ -415,13 +425,13 @@
 }
 
 /*
- * call-seq:
- *   oradate.trunc
+ *  Truncates hour, minute and second fields to zero.
  *
- * Truncates hour, minute and second to zero for <i>oradate</i>.
+ *  @example
+ *    oradate = OraDate.now  # => 2008/07/17 11:07:30
+ *    oradate.trunc          # => 2008/07/17 00:00:00
  *
- *   oradate = OraDate.now   # 2008/07/17 11:07:30
- *   oradate.trunc           # 2008/07/17 00:00:00
+ *  @return [OraDate]
  */
 static VALUE ora_date_trunc(VALUE self)
 {
@@ -435,12 +445,11 @@
 }
 
 /*
- * call-seq:
- *   oradate1 <=> oradate2 -> -1, 0, +1
+ *  call-seq:
+ *     self <=> other
  *
- * Comparison---Compares <i>oradate1</i> with <i>oradate2</i>.
- * Other comparison operators are available because
- * <code>Comparable</code> module is included.
+ *  Returns -1, 0, or +1 depending on whether <i>self</i> is less than,
+ *  equal to, or greater than <i>other</i>.
  */
 static VALUE ora_date_cmp(VALUE self, VALUE val)
 {
@@ -465,7 +474,9 @@
     return INT2FIX(0);
 }
 
-/* :nodoc: */
+/*
+ *  @private
+ */
 static VALUE ora_date_hash(VALUE self)
 {
     ora_date_t *od;
@@ -483,10 +494,11 @@
 }
 
 /*
- * call-seq:
- *   oradate._dump -> string
+ *  Serializes <i>self</i>.
+ *  This method is called by Marshal.dump().
  *
- * Dumps <i>oradate</i> for marshaling.
+ *  @return [String] a byte stream
+ *  @see OraDate._load
  */
 static VALUE ora_date_dump(int argc, VALUE *argv, VALUE self)
 {
@@ -496,10 +508,15 @@
 }
 
 /*
- * call-seq:
- *   OraDate._load(string) -> oradate
+ *  call-seq:
+ *    _load(bytes)
  *
- * Unmarshals a dumped <code>OraDate</code> object.
+ *  Restores a byte stream serialized by {OraDate#_dump}.
+ *  This method is called by Marshal.load() to deserialize a byte stream
+ *  created by Marshal.dump().
+ *
+ *  @param [String] bytes a byte stream
+ *  @return [OraDate] an deserialized object
  */
 static VALUE ora_date_s_load(VALUE klass, VALUE str)
 {
@@ -516,9 +533,9 @@
 }
 
 /*
- * Document-class: OCI8::BindType::OraDate
+ *  Document-class: OCI8::BindType::OraDate
  *
- * This is a helper class to bind OraDate as Oracle's <tt>DATE</tt> datatype.
+ *  This is a helper class to bind OraDate as Oracle's <tt>DATE</tt> datatype.
  *
  */
 static VALUE bind_oradate_get(oci8_bind_t *obind, void *data, void *null_struct)

Modified: trunk/ruby-oci8/lib/oci8/encoding-init.rb
===================================================================
--- trunk/ruby-oci8/lib/oci8/encoding-init.rb	2012-04-05 13:36:06 UTC (rev 500)
+++ trunk/ruby-oci8/lib/oci8/encoding-init.rb	2012-04-06 12:26:57 UTC (rev 501)
@@ -2,6 +2,7 @@
 # setup default OCI encoding from NLS_LANG.
 #
 
+#
 class OCI8
 
   # get the environment variable NLS_LANG.

Modified: trunk/ruby-oci8/lib/oci8/oci8.rb
===================================================================
--- trunk/ruby-oci8/lib/oci8/oci8.rb	2012-04-05 13:36:06 UTC (rev 500)
+++ trunk/ruby-oci8/lib/oci8/oci8.rb	2012-04-06 12:26:57 UTC (rev 501)
@@ -690,6 +690,8 @@
 end # OCI8
 
 class OraDate
+
+  # Returns a Time object which denotes self.
   def to_time
     begin
       Time.local(year, month, day, hour, minute, second)
@@ -699,31 +701,40 @@
     end
   end
 
+  # Returns a Date object which denotes self.
   def to_date
     Date.new(year, month, day)
   end
 
   if defined? DateTime # ruby 1.8.0 or upper
 
-    # get timezone offset.
+    # timezone offset of the time the command started
+    # @private
     @@tz_offset = Time.now.utc_offset.to_r/86400
 
+    # Returns a DateTime object which denotes self.
+    #
+    # Note that this is not daylight saving time aware.
+    # The Time zone offset is that of the time the command started.
     def to_datetime
       DateTime.new(year, month, day, hour, minute, second, @@tz_offset)
     end
   end
 
-  def yaml_initialize(type, val) # :nodoc:
+  # @private
+  def yaml_initialize(type, val)
     initialize(*val.split(/[ -\/:]+/).collect do |i| i.to_i end)
   end
 
-  def to_yaml(opts = {}) # :nodoc:
+  # @private
+  def to_yaml(opts = {})
     YAML.quick_emit(object_id, opts) do |out|
       out.scalar(taguri, self.to_s, :plain)
     end
   end
 
-  def to_json(options=nil) # :nodoc:
+  # @private
+  def to_json(options=nil)
     to_datetime.to_json(options)
   end
 end

Modified: trunk/ruby-oci8/lib/oci8/ocihandle.rb
===================================================================
--- trunk/ruby-oci8/lib/oci8/ocihandle.rb	2012-04-05 13:36:06 UTC (rev 500)
+++ trunk/ruby-oci8/lib/oci8/ocihandle.rb	2012-04-06 12:26:57 UTC (rev 501)
@@ -1,9 +1,9 @@
-#--
 # ocihandle.rb -- Constants in OCIHandle.
 #
-# Copyright (C) 2010 KUBO Takehiro <kubo at jiubao.org>
-#++
+# Copyright (C) 2010-2012 KUBO Takehiro <kubo at jiubao.org>
 
+# The abstract base class to implement common behavior of OCI handle data types and OCI descriptor data types.
+#
 class OCIHandle
 
   #################################
@@ -13,261 +13,393 @@
   #################################
 
   # maximum size of the data
+  # @private
   OCI_ATTR_DATA_SIZE          =   1
 
   # the SQL type of the column/argument
+  # @private
   OCI_ATTR_DATA_TYPE          =   2
   # the name of the column/argument
+  # @private
   OCI_ATTR_NAME               =   4
   # precision if number type
+  # @private
   OCI_ATTR_PRECISION          =   5
   # scale if number type
+  # @private
   OCI_ATTR_SCALE              =   6
   # is it null ?
+  # @private
   OCI_ATTR_IS_NULL            =   7
   # name of the named data type or a package name
+  # @private
   OCI_ATTR_TYPE_NAME          =   8
   # the schema name
+  # @private
   OCI_ATTR_SCHEMA_NAME        =   9
   # type name if package private type
+  # @private
   OCI_ATTR_SUB_NAME           =  10
   # relative position
+  # @private
   OCI_ATTR_POSITION           =  11
   # packed decimal scale
+  # @private
   OCI_ATTR_PDSCL              =  16
   # fs prec for datetime data types
+  # @private
   OCI_ATTR_FSPRECISION        = OCI_ATTR_PDSCL
   # packed decimal format
+  # @private
   OCI_ATTR_PDPRC              =  17
   # fs prec for datetime data types
+  # @private
   OCI_ATTR_LFPRECISION        = OCI_ATTR_PDPRC
   # username attribute
+  # @private
   OCI_ATTR_USERNAME           =  22
   # password attribute
+  # @private
   OCI_ATTR_PASSWORD           =  23
   # Character Set ID
+  # @private
   OCI_ATTR_CHARSET_ID         =  31
   # Character Set Form
+  # @private
   OCI_ATTR_CHARSET_FORM       =  32
   # number of columns
+  # @private
   OCI_ATTR_NUM_COLS           = 102
   # parameter of the column list
+  # @private
   OCI_ATTR_LIST_COLUMNS       = 103
   # DBA of the segment header
+  # @private
   OCI_ATTR_RDBA               = 104
   # whether the table is clustered
+  # @private
   OCI_ATTR_CLUSTERED          = 105
   # whether the table is partitioned
+  # @private
   OCI_ATTR_PARTITIONED        = 106
   # whether the table is index only
+  # @private
   OCI_ATTR_INDEX_ONLY         = 107
   # parameter of the argument list
+  # @private
   OCI_ATTR_LIST_ARGUMENTS     = 108
   # parameter of the subprogram list
+  # @private
   OCI_ATTR_LIST_SUBPROGRAMS   = 109
   # REF to the type descriptor
+  # @private
   OCI_ATTR_REF_TDO            = 110
   # the database link name 
+  # @private
   OCI_ATTR_LINK               = 111
   # minimum value
+  # @private
   OCI_ATTR_MIN                = 112
   # maximum value
+  # @private
   OCI_ATTR_MAX                = 113
   # increment value
+  # @private
   OCI_ATTR_INCR               = 114
   # number of sequence numbers cached
+  # @private
   OCI_ATTR_CACHE              = 115
   # whether the sequence is ordered
+  # @private
   OCI_ATTR_ORDER              = 116
   # high-water mark
+  # @private
   OCI_ATTR_HW_MARK            = 117
   # type's schema name
+  # @private
   OCI_ATTR_TYPE_SCHEMA        = 118
   # timestamp of the object
+  # @private
   OCI_ATTR_TIMESTAMP          = 119
   # number of parameters
+  # @private
   OCI_ATTR_NUM_PARAMS         = 121
   # object id for a table or view
+  # @private
   OCI_ATTR_OBJID              = 122
   # overload ID for funcs and procs
+  # @private
   OCI_ATTR_OVERLOAD_ID        = 125
   # table name space
+  # @private
   OCI_ATTR_TABLESPACE         = 126
   # list type
+  # @private
   OCI_ATTR_LTYPE              = 128
   # whether table is temporary
+  # @private
   OCI_ATTR_IS_TEMPORARY       = 130
   # whether table is typed
+  # @private
   OCI_ATTR_IS_TYPED           = 131
   # duration of temporary table
+  # @private
   OCI_ATTR_DURATION           = 132
   # is invoker rights
+  # @private
   OCI_ATTR_IS_INVOKER_RIGHTS  = 133
   # top level schema obj name
+  # @private
   OCI_ATTR_OBJ_NAME           = 134
   # schema name
+  # @private
   OCI_ATTR_OBJ_SCHEMA         = 135
   # top level schema object id
+  # @private
   OCI_ATTR_OBJ_ID             = 136
 
+  # @private
   OCI_ATTR_CONN_NOWAIT        = 178
+  # @private
   OCI_ATTR_CONN_BUSY_COUNT    = 179
+  # @private
   OCI_ATTR_CONN_OPEN_COUNT    = 180
+  # @private
   OCI_ATTR_CONN_TIMEOUT       = 181
+  # @private
   OCI_ATTR_CONN_MIN           = 183
+  # @private
   OCI_ATTR_CONN_MAX           = 184
+  # @private
   OCI_ATTR_CONN_INCR          = 185
 
   # is this position overloaded
+  # @private
   OCI_ATTR_OVERLOAD           = 210
   # level for structured types
+  # @private
   OCI_ATTR_LEVEL              = 211
   # has a default value
+  # @private
   OCI_ATTR_HAS_DEFAULT        = 212
   # in, out inout
+  # @private
   OCI_ATTR_IOMODE             = 213
   # returns a radix
+  # @private
   OCI_ATTR_RADIX              = 214
   # total number of arguments
+  # @private
   OCI_ATTR_NUM_ARGS           = 215
   # object or collection
+  # @private
   OCI_ATTR_TYPECODE           = 216
   # varray or nested table
+  # @private
   OCI_ATTR_COLLECTION_TYPECODE = 217
   # user assigned version
+  # @private
   OCI_ATTR_VERSION            = 218
   # is this an incomplete type
+  # @private
   OCI_ATTR_IS_INCOMPLETE_TYPE = 219
   # a system type
+  # @private
   OCI_ATTR_IS_SYSTEM_TYPE     = 220
   # a predefined type
+  # @private
   OCI_ATTR_IS_PREDEFINED_TYPE = 221
   # a transient type
+  # @private
   OCI_ATTR_IS_TRANSIENT_TYPE  = 222
   # system generated type
+  # @private
   OCI_ATTR_IS_SYSTEM_GENERATED_TYPE = 223
   # contains nested table attr
+  # @private
   OCI_ATTR_HAS_NESTED_TABLE   = 224
   # has a lob attribute
+  # @private
   OCI_ATTR_HAS_LOB            = 225
   # has a file attribute
+  # @private
   OCI_ATTR_HAS_FILE           = 226
   # has a collection attribute
+  # @private
   OCI_ATTR_COLLECTION_ELEMENT = 227
   # number of attribute types
+  # @private
   OCI_ATTR_NUM_TYPE_ATTRS     = 228
   # list of type attributes
+  # @private
   OCI_ATTR_LIST_TYPE_ATTRS    = 229
   # number of type methods
+  # @private
   OCI_ATTR_NUM_TYPE_METHODS   = 230
   # list of type methods
+  # @private
   OCI_ATTR_LIST_TYPE_METHODS  = 231
   # map method of type
+  # @private
   OCI_ATTR_MAP_METHOD         = 232
   # order method of type 
+  # @private
   OCI_ATTR_ORDER_METHOD       = 233
   # number of elements
+  # @private
   OCI_ATTR_NUM_ELEMS          = 234
   # encapsulation level
+  # @private
   OCI_ATTR_ENCAPSULATION      = 235
   # method selfish
+  # @private
   OCI_ATTR_IS_SELFISH         = 236
   # virtual
+  # @private
   OCI_ATTR_IS_VIRTUAL         = 237
   # inline
+  # @private
   OCI_ATTR_IS_INLINE          = 238
   # constant
+  # @private
   OCI_ATTR_IS_CONSTANT        = 239
   # has result
+  # @private
   OCI_ATTR_HAS_RESULT         = 240
   # constructor
+  # @private
   OCI_ATTR_IS_CONSTRUCTOR     = 241
   # destructor
+  # @private
   OCI_ATTR_IS_DESTRUCTOR      = 242
   # operator
+  # @private
   OCI_ATTR_IS_OPERATOR        = 243
   # a map method
+  # @private
   OCI_ATTR_IS_MAP             = 244
   # order method
+  # @private
   OCI_ATTR_IS_ORDER           = 245
   # read no data state method
+  # @private
   OCI_ATTR_IS_RNDS            = 246
   # read no process state
+  # @private
   OCI_ATTR_IS_RNPS            = 247
   # write no data state method
+  # @private
   OCI_ATTR_IS_WNDS            = 248
   # write no process state
+  # @private
   OCI_ATTR_IS_WNPS            = 249
+  # @private
   OCI_ATTR_IS_SUBTYPE         = 258
+  # @private
   OCI_ATTR_SUPERTYPE_SCHEMA_NAME = 259
+  # @private
   OCI_ATTR_SUPERTYPE_NAME     = 260
   # list of objects in schema
+  # @private
   OCI_ATTR_LIST_OBJECTS       = 261
   # char set id
+  # @private
   OCI_ATTR_NCHARSET_ID        = 262
   # list of schemas
+  # @private
   OCI_ATTR_LIST_SCHEMAS       = 263
   # max procedure length
+  # @private
   OCI_ATTR_MAX_PROC_LEN       = 264
   # max column name length
+  # @private
   OCI_ATTR_MAX_COLUMN_LEN     = 265
   # cursor commit behavior
+  # @private
   OCI_ATTR_CURSOR_COMMIT_BEHAVIOR = 266
   # catalog namelength
+  # @private
   OCI_ATTR_MAX_CATALOG_NAMELEN = 267
   # catalog location
+  # @private
   OCI_ATTR_CATALOG_LOCATION   = 268
   # savepoint support
+  # @private
   OCI_ATTR_SAVEPOINT_SUPPORT  = 269
   # nowait support
+  # @private
   OCI_ATTR_NOWAIT_SUPPORT     = 270
   # autocommit DDL
+  # @private
   OCI_ATTR_AUTOCOMMIT_DDL     = 271
   # locking mode
+  # @private
   OCI_ATTR_LOCKING_MODE       = 272
   # value of client id to set
+  # @private
   OCI_ATTR_CLIENT_IDENTIFIER  = 278
   # is final type ?
+  # @private
   OCI_ATTR_IS_FINAL_TYPE      = 279
   # is instantiable type ?
+  # @private
   OCI_ATTR_IS_INSTANTIABLE_TYPE = 280
   # is final method ?
+  # @private
   OCI_ATTR_IS_FINAL_METHOD    = 281
   # is instantiable method ?
+  # @private
   OCI_ATTR_IS_INSTANTIABLE_METHOD = 282
   # is overriding method ?
+  # @private
   OCI_ATTR_IS_OVERRIDING_METHOD = 283
   # Describe the base object
+  # @private
   OCI_ATTR_DESC_SYNBASE       = 284
   # char length semantics
+  # @private
   OCI_ATTR_CHAR_USED          = 285
   # char length
+  # @private
   OCI_ATTR_CHAR_SIZE          = 286
   # rule condition
+  # @private
   OCI_ATTR_CONDITION          = 342
   # comment
+  # @private
   OCI_ATTR_COMMENT            = 343
   # Anydata value
+  # @private
   OCI_ATTR_VALUE              = 344
   # eval context owner
+  # @private
   OCI_ATTR_EVAL_CONTEXT_OWNER = 345
   # eval context name
+  # @private
   OCI_ATTR_EVAL_CONTEXT_NAME  = 346
   # eval function name
+  # @private
   OCI_ATTR_EVALUATION_FUNCTION = 347
   # variable type
+  # @private
   OCI_ATTR_VAR_TYPE           = 348
   # variable value function
+  # @private
   OCI_ATTR_VAR_VALUE_FUNCTION = 349
   # variable method function
+  # @private
   OCI_ATTR_VAR_METHOD_FUNCTION = 350
   # action context
+  # @private
   OCI_ATTR_ACTION_CONTEXT     = 351
   # list of table aliases
+  # @private
   OCI_ATTR_LIST_TABLE_ALIASES = 352
   # list of variable types
+  # @private
   OCI_ATTR_LIST_VARIABLE_TYPES = 353
   # table name
+  # @private
   OCI_ATTR_TABLE_NAME         = 356
 
   #################################
@@ -277,6 +409,7 @@
   #################################
 
   # the default value for parameters and attributes
+  # @private
   OCI_DEFAULT                 =   0
 
   #################################
@@ -286,8 +419,10 @@
   #################################
 
   # database username/password credentials
+  # @private
   OCI_CRED_RDBMS              =   1
   # externally provided credentials
+  # @private
   OCI_CRED_EXT                =   2
 
   #################################
@@ -297,76 +432,95 @@
   #################################
 
   # for SYSDBA authorization
+  # @private
   OCI_SYSDBA                  = 0x0002
   # for SYSOPER authorization
+  # @private
   OCI_SYSOPER                 = 0x0004
   # for SYSASM authorization
+  # @private
   OCI_SYSASM                  = 0x8000
 
   #################################
   #
-  # Attach Modes
-  #
-  #################################
-
-  # Attach using server handle from pool
-  OCI_CPOOL                   = 0x0200
-
-  #################################
-  #
   # OCI Parameter Types
   #
   #################################
 
   # parameter type for unknown type
+  # @private
   OCI_PTYPE_UNK               =  0
   # parameter type for table
+  # @private
   OCI_PTYPE_TABLE             =  1
   # parameter type for view
+  # @private
   OCI_PTYPE_VIEW              =  2
   # parameter type for procedure
+  # @private
   OCI_PTYPE_PROC              =  3
   # parameter type for function
+  # @private
   OCI_PTYPE_FUNC              =  4
   # parameter type for package
+  # @private
   OCI_PTYPE_PKG               =  5
   # parameter type for user-defined type
+  # @private
   OCI_PTYPE_TYPE              =  6
   # parameter type for synonym
+  # @private
   OCI_PTYPE_SYN               =  7
   # parameter type for sequence
+  # @private
   OCI_PTYPE_SEQ               =  8
   # parameter type for column
+  # @private
   OCI_PTYPE_COL               =  9
   # parameter type for argument
+  # @private
   OCI_PTYPE_ARG               = 10
   # parameter type for list
+  # @private
   OCI_PTYPE_LIST              = 11
   # parameter type for user-defined type's attribute
+  # @private
   OCI_PTYPE_TYPE_ATTR         = 12
   # parameter type for collection type's element
+  # @private
   OCI_PTYPE_TYPE_COLL         = 13
   # parameter type for user-defined type's method
+  # @private
   OCI_PTYPE_TYPE_METHOD       = 14
   # parameter type for user-defined type method's arg
+  # @private
   OCI_PTYPE_TYPE_ARG          = 15
   # parameter type for user-defined type method's result
+  # @private
   OCI_PTYPE_TYPE_RESULT       = 16
   # parameter type for schema
+  # @private
   OCI_PTYPE_SCHEMA            = 17
   # parameter type for database
+  # @private
   OCI_PTYPE_DATABASE          = 18
   # parameter type for rule
+  # @private
   OCI_PTYPE_RULE              = 19
   # parameter type for rule set
+  # @private
   OCI_PTYPE_RULE_SET          = 20
   # parameter type for evaluation context
+  # @private
   OCI_PTYPE_EVALUATION_CONTEXT = 21
   # parameter type for table alias
+  # @private
   OCI_PTYPE_TABLE_ALIAS       = 22
   # parameter type for variable type
+  # @private
   OCI_PTYPE_VARIABLE_TYPE     = 23
   # parameter type for name value pair
+  # @private
   OCI_PTYPE_NAME_VALUE        = 24
 
   #################################
@@ -376,34 +530,49 @@
   #################################
 
   # list type for unknown type
+  # @private
   OCI_LTYPE_UNK                =  0
   # list type for column list
+  # @private
   OCI_LTYPE_COLUMN             =  1
   # list type for procedure argument list
+  # @private
   OCI_LTYPE_ARG_PROC           =  2
   # list type for function argument list
+  # @private
   OCI_LTYPE_ARG_FUNC           =  3
   # list type for subprogram list
+  # @private
   OCI_LTYPE_SUBPRG             =  4
   # list type for type attribute
+  # @private
   OCI_LTYPE_TYPE_ATTR          =  5
   # list type for type method
+  # @private
   OCI_LTYPE_TYPE_METHOD        =  6
   # list type for type method w/o result argument list
+  # @private
   OCI_LTYPE_TYPE_ARG_PROC      =  7
   # list type for type method w/result argument list
+  # @private
   OCI_LTYPE_TYPE_ARG_FUNC      =  8
   # list type for schema object list
+  # @private
   OCI_LTYPE_SCH_OBJ            =  9
   # list type for database schema list
+  # @private
   OCI_LTYPE_DB_SCH             = 10
   # list type for subtype list
+  # @private
   OCI_LTYPE_TYPE_SUBTYPE       = 11
   # list type for table alias list
+  # @private
   OCI_LTYPE_TABLE_ALIAS        = 12
   # list type for variable type list
+  # @private
   OCI_LTYPE_VARIABLE_TYPE      = 13
   # list type for name value list
+  # @private
   OCI_LTYPE_NAME_VALUE         = 14
 
   #################################
@@ -413,15 +582,26 @@
   #################################
 
   #
+  # @private
   OCI_DURATION_INVALID       = 0xFFFF
+  # @private
   OCI_DURATION_BEGIN         = 10
+  # @private
   OCI_DURATION_NULL          = OCI_DURATION_BEGIN - 1
+  # @private
   OCI_DURATION_DEFAULT       = OCI_DURATION_BEGIN - 2
+  # @private
   OCI_DURATION_USER_CALLBACK = OCI_DURATION_BEGIN - 3
+  # @private
   OCI_DURATION_NEXT          = OCI_DURATION_BEGIN - 4
+  # @private
   OCI_DURATION_SESSION       = OCI_DURATION_BEGIN
+  # @private
   OCI_DURATION_TRANS         = OCI_DURATION_BEGIN + 1
+  # @private
   OCI_DURATION_CALL          = OCI_DURATION_BEGIN + 2
+  # @private
   OCI_DURATION_STATEMENT     = OCI_DURATION_BEGIN + 3
+  # @private
   OCI_DURATION_CALLOUT       = OCI_DURATION_BEGIN + 4
 end


From nobody at rubyforge.org  Sun Apr  8 11:32:56 2012
From: nobody at rubyforge.org (nobody at rubyforge.org)
Date: Sun,  8 Apr 2012 11:32:56 +0000 (UTC)
Subject: [ruby-oci8-commit] [502] trunk/ruby-oci8: revise rdoc comments.
Message-ID: <20120408113256.5F1C226303F@rubyforge.org>

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


From nobody at rubyforge.org  Tue Apr 17 11:15:49 2012
From: nobody at rubyforge.org (nobody at rubyforge.org)
Date: Tue, 17 Apr 2012 11:15:49 +0000 (UTC)
Subject: [ruby-oci8-commit] [503] trunk/ruby-oci8: fix core dump.
Message-ID: <20120417111549.B500F263048@rubyforge.org>

Revision: 503
Author:   kubo
Date:     2012-04-17 11:15:49 +0000 (Tue, 17 Apr 2012)
Log Message:
-----------
fix core dump.
See: https://github.com/kubo/ruby-oci8/issues/11

Modified Paths:
--------------
    trunk/ruby-oci8/ChangeLog
    trunk/ruby-oci8/ext/oci8/oci8lib.c

Modified: trunk/ruby-oci8/ChangeLog
===================================================================
--- trunk/ruby-oci8/ChangeLog	2012-04-08 11:32:55 UTC (rev 502)
+++ trunk/ruby-oci8/ChangeLog	2012-04-17 11:15:49 UTC (rev 503)
@@ -1,3 +1,8 @@
+2012-04-17  KUBO Takehiro  <kubo at jiubao.org>
+	* ext/oci8/oci8lib.c: fix core dump.
+	    See: https://github.com/kubo/ruby-oci8/issues/11
+	    (reported by Raimonds Simanovskis)
+
 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.

Modified: trunk/ruby-oci8/ext/oci8/oci8lib.c
===================================================================
--- trunk/ruby-oci8/ext/oci8/oci8lib.c	2012-04-08 11:32:55 UTC (rev 502)
+++ trunk/ruby-oci8/ext/oci8/oci8lib.c	2012-04-17 11:15:49 UTC (rev 503)
@@ -37,10 +37,15 @@
     oci8_unlink_from_parent(base);
     if (base->vptr->free != NULL)
         base->vptr->free(base);
-    if (base->type >= OCI_DTYPE_FIRST)
+    if (base->type >= OCI_DTYPE_FIRST) {
         OCIDescriptorFree(base->hp.ptr, base->type);
-    else if (base->type >= OCI_HTYPE_FIRST)
+    } else if (base->type == OCI_HTYPE_BIND || base->type == OCI_HTYPE_DEFINE) {
+        ; /* Do nothing. Bind handles and define handles are freed when
+           * associating statement handles are freed.
+           */
+    } else if (base->type >= OCI_HTYPE_FIRST) {
         OCIHandleFree(base->hp.ptr, base->type);
+    }
     base->type = 0;
     base->hp.ptr = NULL;
 }


From nobody at rubyforge.org  Tue Apr 17 12:16:24 2012
From: nobody at rubyforge.org (nobody at rubyforge.org)
Date: Tue, 17 Apr 2012 12:16:24 +0000 (UTC)
Subject: [ruby-oci8-commit] [504] trunk/ruby-oci8: 1. fix an exception when
 OCI8::CLOB.new(conn, '')  is called.
Message-ID: <20120417121624.0FB6B263035@rubyforge.org>

Revision: 504
Author:   kubo
Date:     2012-04-17 12:16:23 +0000 (Tue, 17 Apr 2012)
Log Message:
-----------
1. fix an exception when OCI8::CLOB.new(conn, '') is called.
2. Reset the position of a newly created LOB.

Modified Paths:
--------------
    trunk/ruby-oci8/ChangeLog
    trunk/ruby-oci8/ext/oci8/lob.c

Modified: trunk/ruby-oci8/ChangeLog
===================================================================
--- trunk/ruby-oci8/ChangeLog	2012-04-17 11:15:49 UTC (rev 503)
+++ trunk/ruby-oci8/ChangeLog	2012-04-17 12:16:23 UTC (rev 504)
@@ -1,4 +1,8 @@
 2012-04-17  KUBO Takehiro  <kubo at jiubao.org>
+	* ext/oci8/lob.c: 1. fix an exception when OCI8::CLOB.new(conn, '')
+	    is called. 2. Reset the position of a newly created LOB.
+
+2012-04-17  KUBO Takehiro  <kubo at jiubao.org>
 	* ext/oci8/oci8lib.c: fix core dump.
 	    See: https://github.com/kubo/ruby-oci8/issues/11
 	    (reported by Raimonds Simanovskis)

Modified: trunk/ruby-oci8/ext/oci8/lob.c
===================================================================
--- trunk/ruby-oci8/ext/oci8/lob.c	2012-04-17 11:15:49 UTC (rev 503)
+++ trunk/ruby-oci8/ext/oci8/lob.c	2012-04-17 12:16:23 UTC (rev 504)
@@ -1,4 +1,4 @@
-/* -*- c-file-style: "ruby"; indent-tabs-mode: nil -*- */
+o/* -*- c-file-style: "ruby"; indent-tabs-mode: nil -*- */
 #include "oci8.h"
 
 static ID id_plus;
@@ -234,6 +234,7 @@
                &svcctx->base);
         lob->svchp = oci8_get_oci_svcctx(svc);
         oci8_lob_write(self, val);
+        lob->pos = 0; /* reset the position */
     }
     return Qnil;
 }
@@ -601,6 +602,10 @@
     }
     RB_GC_GUARD(data);
     amt = RSTRING_LEN(data);
+    if (amt == 0) {
+        /* to avoid ORA-24801: illegal parameter value in OCI lob function */
+        return INT2FIX(0);
+    }
     chker2(OCILobWrite_nb(svcctx, svcctx->base.hp.svc, oci8_errhp, lob->base.hp.lob, &amt, lob->pos + 1, RSTRING_PTR(data), amt, OCI_ONE_PIECE, NULL, NULL, 0, lob->csfrm),
            &svcctx->base);
     lob->pos += amt;


From nobody at rubyforge.org  Tue Apr 17 12:26:15 2012
From: nobody at rubyforge.org (nobody at rubyforge.org)
Date: Tue, 17 Apr 2012 12:26:15 +0000 (UTC)
Subject: [ruby-oci8-commit] [505] trunk/ruby-oci8/ext/oci8/lob.c: fix failed
	commit.
Message-ID: <20120417122615.38BA7263035@rubyforge.org>

Revision: 505
Author:   kubo
Date:     2012-04-17 12:26:15 +0000 (Tue, 17 Apr 2012)
Log Message:
-----------
fix failed commit.

Modified Paths:
--------------
    trunk/ruby-oci8/ext/oci8/lob.c

Modified: trunk/ruby-oci8/ext/oci8/lob.c
===================================================================
--- trunk/ruby-oci8/ext/oci8/lob.c	2012-04-17 12:16:23 UTC (rev 504)
+++ trunk/ruby-oci8/ext/oci8/lob.c	2012-04-17 12:26:15 UTC (rev 505)
@@ -1,4 +1,4 @@
-o/* -*- c-file-style: "ruby"; indent-tabs-mode: nil -*- */
+/* -*- c-file-style: "ruby"; indent-tabs-mode: nil -*- */
 #include "oci8.h"
 
 static ID id_plus;


From nobody at rubyforge.org  Sat Apr 21 04:59:18 2012
From: nobody at rubyforge.org (nobody at rubyforge.org)
Date: Sat, 21 Apr 2012 04:59:18 +0000 (UTC)
Subject: [ruby-oci8-commit] [506] trunk/ruby-oci8: fix code to test
	OCI8::CLOB.new(conn, '').
Message-ID: <20120421045918.4C3B73AFF5@rubyforge.org>

Revision: 506
Author:   kubo
Date:     2012-04-21 04:59:17 +0000 (Sat, 21 Apr 2012)
Log Message:
-----------
fix code to test OCI8::CLOB.new(conn, '').

Modified Paths:
--------------
    trunk/ruby-oci8/ChangeLog
    trunk/ruby-oci8/test/test_oci8.rb

Modified: trunk/ruby-oci8/ChangeLog
===================================================================
--- trunk/ruby-oci8/ChangeLog	2012-04-17 12:26:15 UTC (rev 505)
+++ trunk/ruby-oci8/ChangeLog	2012-04-21 04:59:17 UTC (rev 506)
@@ -1,3 +1,6 @@
+2012-04-21  KUBO Takehiro  <kubo at jiubao.org>
+	* test/test_oci8.rb: fix code to test OCI8::CLOB.new(conn, '').
+
 2012-04-17  KUBO Takehiro  <kubo at jiubao.org>
 	* ext/oci8/lob.c: 1. fix an exception when OCI8::CLOB.new(conn, '')
 	    is called. 2. Reset the position of a newly created LOB.

Modified: trunk/ruby-oci8/test/test_oci8.rb
===================================================================
--- trunk/ruby-oci8/test/test_oci8.rb	2012-04-17 12:26:15 UTC (rev 505)
+++ trunk/ruby-oci8/test/test_oci8.rb	2012-04-21 04:59:17 UTC (rev 506)
@@ -322,14 +322,20 @@
     @conn.exec(sql)
     cursor = @conn.parse("INSERT INTO test_table VALUES (:1, :2, :3, :4)")
     0.upto(9) do |i|
-      val = format('%d', i) * 4096
+      val = case i
+            when 5; '' # empty string
+            else format('%d', i) * 4096
+            end
       cursor.exec(i, OCI8::CLOB.new(@conn, val), OCI8::NCLOB.new(@conn, val), OCI8::BLOB.new(@conn, val))
     end
     cursor.close
     cursor = @conn.exec("select * from test_table order by id")
     0.upto(9) do |i|
       rv = cursor.fetch
-      val = format('%d', i) * 4096
+      val = case i
+            when 5; '' # empty string
+            else format('%d', i) * 4096
+            end
       assert_equal(i, rv[0])
       assert_instance_of(OCI8::CLOB, rv[1])
       assert_instance_of(OCI8::NCLOB, rv[2])


From nobody at rubyforge.org  Sat Apr 21 05:02:53 2012
From: nobody at rubyforge.org (nobody at rubyforge.org)
Date: Sat, 21 Apr 2012 05:02:53 +0000 (UTC)
Subject: [ruby-oci8-commit] [507] trunk/ruby-oci8: delete an unused file.
Message-ID: <20120421050253.1478A3AFF5@rubyforge.org>

Revision: 507
Author:   kubo
Date:     2012-04-21 05:02:52 +0000 (Sat, 21 Apr 2012)
Log Message:
-----------
delete an unused file.

Modified Paths:
--------------
    trunk/ruby-oci8/ChangeLog

Removed Paths:
-------------
    trunk/ruby-oci8/custom-rdoc.rb

Modified: trunk/ruby-oci8/ChangeLog
===================================================================
--- trunk/ruby-oci8/ChangeLog	2012-04-21 04:59:17 UTC (rev 506)
+++ trunk/ruby-oci8/ChangeLog	2012-04-21 05:02:52 UTC (rev 507)
@@ -1,4 +1,7 @@
 2012-04-21  KUBO Takehiro  <kubo at jiubao.org>
+	* custom-rdoc.rb: delete an unused file.
+
+2012-04-21  KUBO Takehiro  <kubo at jiubao.org>
 	* test/test_oci8.rb: fix code to test OCI8::CLOB.new(conn, '').
 
 2012-04-17  KUBO Takehiro  <kubo at jiubao.org>

Deleted: trunk/ruby-oci8/custom-rdoc.rb
===================================================================
--- trunk/ruby-oci8/custom-rdoc.rb	2012-04-21 04:59:17 UTC (rev 506)
+++ trunk/ruby-oci8/custom-rdoc.rb	2012-04-21 05:02:52 UTC (rev 507)
@@ -1,46 +0,0 @@
-require 'rdoc/rdoc'
-
-if defined? RDoc::Parser::C
-  c_parser = RDoc::Parser::C
-elsif defined? RDoc::C_Parser
-  c_parser = RDoc::C_Parser
-end
-
-c_parser.module_eval do
-  alias :do_classes_orig :do_classes
-  def do_classes
-    content = (defined? @content) && @content || @body
-
-    # oci8_cOCIHandle = rb_define_class("OCIHandle", rb_cObject)
-    handle_class_module('oci8_cOCIHandle', 'class', 'OCIHandle', 'rb_cObject', nil)
-    # cOCI8 = rb_define_class("OCI8", oci8_cOCIHandle)
-    handle_class_module('cOCI8', 'class', 'OCI8', 'oci8_cOCIHandle', nil)
-    # mOCI8BindType = rb_define_module_under(cOCI8, "BindType");
-    handle_class_module('mOCI8BindType', 'module', 'BindType', nil, 'cOCI8')
-    # cOCI8BindTypeBase = rb_define_class_under(mOCI8BindType, "Base", oci8_cOCIHandle);
-    handle_class_module('cOCI8BindTypeBase', 'class', 'Base', nil, 'mOCI8BindType')
-
-    # var_name = oci8_define_class_under(in_module, "class_name", &xxxx);
-    content.scan(/(\w+)\s*=\s*oci8_define_class_under\s*\(\s*(\w+)\s*,\s*"(\w+)",\s*&\w+?\s*\)/) do
-      |var_name, in_module, class_name|
-      handle_class_module(var_name, "class", class_name, 'oci8_cOCIHandle', in_module)
-    end
-
-    # var_name = oci8_define_bind_class("class_name", &xxxx);
-    content.scan(/(?:(\w+)\s*=\s*)?oci8_define_bind_class\s*\(\s*"(\w+)",\s*&\w+?\s*\)/) do
-      |var_name, class_name|
-      var_name ||= 'dummy'
-      handle_class_module(var_name, "class", class_name, 'cOCI8BindTypeBase', 'mOCI8BindType')
-    end
-
-    do_classes_orig
-  end
-end
-
-begin
-  r = RDoc::RDoc.new
-  r.document(ARGV)
-rescue RDoc::RDocError => e
-  $stderr.puts e.message
-  exit(1)
-end


From nobody at rubyforge.org  Sat Apr 21 06:26:27 2012
From: nobody at rubyforge.org (nobody at rubyforge.org)
Date: Sat, 21 Apr 2012 06:26:27 +0000 (UTC)
Subject: [ruby-oci8-commit] [508] trunk/ruby-oci8: OCI8::LOB#read() returns
 an empty string '' when it is an empty lob.
Message-ID: <20120421062627.233243AFF5@rubyforge.org>

Revision: 508
Author:   kubo
Date:     2012-04-21 06:26:26 +0000 (Sat, 21 Apr 2012)
Log Message:
-----------
OCI8::LOB#read() returns an empty string '' when it is an empty lob.

Modified Paths:
--------------
    trunk/ruby-oci8/ChangeLog
    trunk/ruby-oci8/ext/oci8/lob.c

Modified: trunk/ruby-oci8/ChangeLog
===================================================================
--- trunk/ruby-oci8/ChangeLog	2012-04-21 05:02:52 UTC (rev 507)
+++ trunk/ruby-oci8/ChangeLog	2012-04-21 06:26:26 UTC (rev 508)
@@ -1,4 +1,8 @@
 2012-04-21  KUBO Takehiro  <kubo at jiubao.org>
+	* ext/oci8/lob.c: OCI8::LOB#read() returns an empty string '' when
+	    it is an empty lob.
+
+2012-04-21  KUBO Takehiro  <kubo at jiubao.org>
 	* custom-rdoc.rb: delete an unused file.
 
 2012-04-21  KUBO Takehiro  <kubo at jiubao.org>

Modified: trunk/ruby-oci8/ext/oci8/lob.c
===================================================================
--- trunk/ruby-oci8/ext/oci8/lob.c	2012-04-21 05:02:52 UTC (rev 507)
+++ trunk/ruby-oci8/ext/oci8/lob.c	2012-04-21 06:26:26 UTC (rev 508)
@@ -473,10 +473,14 @@
  *
  *  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.
+ *  If <i>length</i> is <code>nil</code>, it reads data until EOF.
  *
+ *  It returns a string or <code>nil</code>. <code>nil</code> means it
+ *  met EOF at beginning. As a special exception, when <i>length</i> is
+ *  <code>nil</code> and the lob length is zero, it returns an empty string ''.
+ *
  *  @param [Integer] length
- *  @return [String]
+ *  @return [String or nil]
  */
 static VALUE oci8_lob_read(int argc, VALUE *argv, VALUE self)
 {
@@ -493,6 +497,9 @@
 
     rb_scan_args(argc, argv, "01", &size);
     length = oci8_lob_get_length(lob);
+    if (length == 0 && NIL_P(size)) {
+        return rb_usascii_str_new("", 0);
+    }
     if (length <= lob->pos) /* EOF */
         return Qnil;
     length -= lob->pos;


From nobody at rubyforge.org  Sat Apr 21 10:57:50 2012
From: nobody at rubyforge.org (nobody at rubyforge.org)
Date: Sat, 21 Apr 2012 10:57:50 +0000 (UTC)
Subject: [ruby-oci8-commit] [509] trunk/ruby-oci8: fix to raise a
 RuntimeError when a connection retrieved from a connection pool is set as
 non-blocking on ruby 1 .8.
Message-ID: <20120421105750.53E9D3AFF5@rubyforge.org>

Revision: 509
Author:   kubo
Date:     2012-04-21 10:57:49 +0000 (Sat, 21 Apr 2012)
Log Message:
-----------
fix to raise a RuntimeError when a connection retrieved from a connection pool is set as non-blocking on ruby 1.8.

Modified Paths:
--------------
    trunk/ruby-oci8/ChangeLog
    trunk/ruby-oci8/ext/oci8/oci8.c

Modified: trunk/ruby-oci8/ChangeLog
===================================================================
--- trunk/ruby-oci8/ChangeLog	2012-04-21 06:26:26 UTC (rev 508)
+++ trunk/ruby-oci8/ChangeLog	2012-04-21 10:57:49 UTC (rev 509)
@@ -1,4 +1,9 @@
 2012-04-21  KUBO Takehiro  <kubo at jiubao.org>
+	* ext/oci8/oci8.c: fix to raise a RuntimeError when a connection
+	    retrieved from a connection pool is set as non-blocking on 
+	    ruby 1.8.
+
+2012-04-21  KUBO Takehiro  <kubo at jiubao.org>
 	* ext/oci8/lob.c: OCI8::LOB#read() returns an empty string '' when
 	    it is an empty lob.
 

Modified: trunk/ruby-oci8/ext/oci8/oci8.c
===================================================================
--- trunk/ruby-oci8/ext/oci8/oci8.c	2012-04-21 06:26:26 UTC (rev 508)
+++ trunk/ruby-oci8/ext/oci8/oci8.c	2012-04-21 10:57:49 UTC (rev 509)
@@ -338,6 +338,7 @@
 static VALUE oci8_logon2(VALUE self, VALUE username, VALUE password, VALUE dbname, VALUE mode)
 {
     oci8_svcctx_t *svcctx = DATA_PTR(self);
+    ub4 logon2_mode;
 
     if (svcctx->logoff_strategy != NULL) {
         rb_raise(rb_eRuntimeError, "Could not reuse the session.");
@@ -349,6 +350,7 @@
     if (!NIL_P(dbname)) {
         OCI8SafeStringValue(dbname);
     }
+    logon2_mode = NUM2UINT(mode);
 
     /* logon */
     svcctx->base.type = OCI_HTYPE_SVCCTX;
@@ -356,10 +358,14 @@
                         RSTRING_ORATEXT(username), RSTRING_LEN(username),
                         RSTRING_ORATEXT(password), RSTRING_LEN(password),
                         NIL_P(dbname) ? NULL : RSTRING_ORATEXT(dbname),
-                        NIL_P(dbname) ? 0 : RSTRING_LEN(dbname), NUM2UINT(mode)),
+                        NIL_P(dbname) ? 0 : RSTRING_LEN(dbname), logon2_mode),
            &svcctx->base);
     svcctx->logoff_strategy = &simple_logoff;
 
+    if (logon2_mode & OCI_LOGON2_CPOOL) {
+        svcctx->state |= OCI8_STATE_CPOOL;
+    }
+
     /* setup the session handle */
     chker2(OCIAttrGet(svcctx->base.hp.ptr, OCI_HTYPE_SVCCTX, &svcctx->usrhp, 0, OCI_ATTR_SESSION, oci8_errhp),
            &svcctx->base);


From nobody at rubyforge.org  Sat Apr 21 12:03:15 2012
From: nobody at rubyforge.org (nobody at rubyforge.org)
Date: Sat, 21 Apr 2012 12:03:15 +0000 (UTC)
Subject: [ruby-oci8-commit] [510] trunk/ruby-oci8: fix to pass tests on ruby
	1.9.1 and earlier.
Message-ID: <20120421120315.D6163263035@rubyforge.org>

Revision: 510
Author:   kubo
Date:     2012-04-21 12:03:15 +0000 (Sat, 21 Apr 2012)
Log Message:
-----------
fix to pass tests on ruby 1.9.1 and earlier.

Modified Paths:
--------------
    trunk/ruby-oci8/ChangeLog
    trunk/ruby-oci8/test/test_datetime.rb

Modified: trunk/ruby-oci8/ChangeLog
===================================================================
--- trunk/ruby-oci8/ChangeLog	2012-04-21 10:57:49 UTC (rev 509)
+++ trunk/ruby-oci8/ChangeLog	2012-04-21 12:03:15 UTC (rev 510)
@@ -1,4 +1,7 @@
 2012-04-21  KUBO Takehiro  <kubo at jiubao.org>
+	* test/test_datetime.rb: fix to pass tests on ruby 1.9.1 and earlier.
+
+2012-04-21  KUBO Takehiro  <kubo at jiubao.org>
 	* ext/oci8/oci8.c: fix to raise a RuntimeError when a connection
 	    retrieved from a connection pool is set as non-blocking on 
 	    ruby 1.8.

Modified: trunk/ruby-oci8/test/test_datetime.rb
===================================================================
--- trunk/ruby-oci8/test/test_datetime.rb	2012-04-21 10:57:49 UTC (rev 509)
+++ trunk/ruby-oci8/test/test_datetime.rb	2012-04-21 12:03:15 UTC (rev 510)
@@ -13,15 +13,22 @@
     end
   end
 
+  @@time_new_accepts_timezone = begin
+                                  Time.new(2001, 1, 1, 0, 0, 0, '+00:00')
+                                  true
+                                rescue
+                                  false
+                                end
+
   def string_to_time(str)
-    /(\d+)-(\d+)-(\d+) ?(?:(\d+):(\d+):(\d+))?(?:\.(\d+))? ?([+-]\d+:\d+)?/ =~ str
+    /(\d+)-(\d+)-(\d+) ?(?:(\d+):(\d+):(\d+))?(?:\.(\d+))? ?(([+-])(\d+):(\d+))?/ =~ str
     args = []
     args << $1.to_i # year
     args << $2.to_i # month
     args << $3.to_i # day
     args << $4.to_i if $4 # hour
     args << $5.to_i if $5 # minute
-    if $8
+    if $8 and @@time_new_accepts_timezone
       args << $6.to_i + $7.to_i.to_r / ('1' + '0' * ($7.length)).to_i
       args << $8
       Time.new(*args)
@@ -32,8 +39,20 @@
       if $7
         args << $7.to_i.to_r * 1000000 / ('1' + '0' * ($7.length)).to_i
       end
-      # no time zone
-      Time.local(*args)
+      if $8
+        # with time zone
+        offset = ($9 + '1').to_i * ($10.to_i * 60 + $11.to_i)
+        if offset == 0
+          Time.utc(*args)
+        else
+          tm = Time.local(*args)
+          raise "Failed to convert #{str} to Time" if tm.utc_offset != offset * 60
+          tm
+        end
+      else
+        # without time zone
+        Time.local(*args)
+      end
     end
     #Time.local(*str.split(/[- :\.]/).collect do |n| n.to_i; end)
   end


From nobody at rubyforge.org  Sun Apr 22 09:56:15 2012
From: nobody at rubyforge.org (nobody at rubyforge.org)
Date: Sun, 22 Apr 2012 09:56:15 +0000 (UTC)
Subject: [ruby-oci8-commit] [511] trunk/ruby-oci8: fix documents
Message-ID: <20120422095616.1CC52263041@rubyforge.org>

Revision: 511
Author:   kubo
Date:     2012-04-22 09:56:15 +0000 (Sun, 22 Apr 2012)
Log Message:
-----------
fix documents

Modified Paths:
--------------
    trunk/ruby-oci8/ChangeLog
    trunk/ruby-oci8/NEWS
    trunk/ruby-oci8/dist-files
    trunk/ruby-oci8/docs/platform-specific-issues.md
    trunk/ruby-oci8/lib/oci8/bindtype.rb
    trunk/ruby-oci8/lib/oci8/connection_pool.rb
    trunk/ruby-oci8/lib/oci8/object.rb
    trunk/ruby-oci8/lib/oci8/properties.rb
    trunk/ruby-oci8/ruby-oci8.gemspec

Added Paths:
-----------
    trunk/ruby-oci8/.yardopts
    trunk/ruby-oci8/README.md
    trunk/ruby-oci8/docs/install-binary-package.md
    trunk/ruby-oci8/docs/report-installation-issue.md

Removed Paths:
-------------
    trunk/ruby-oci8/README

Added: trunk/ruby-oci8/.yardopts
===================================================================
--- trunk/ruby-oci8/.yardopts	                        (rev 0)
+++ trunk/ruby-oci8/.yardopts	2012-04-22 09:56:15 UTC (rev 511)
@@ -0,0 +1,13 @@
+--protected
+--no-private
+--exclude ext/oci8/apiwrap.rb
+--exclude ext/oci8/oraconf.rb
+--exclude lib/oci8/compat.rb
+--exclude lib/dbd
+-
+NEWS
+docs/install-full-client.md
+docs/install-instant-client.md
+docs/install-binary-package.md
+docs/platform-specific-issues.md
+docs/report-installation-issue.md

Modified: trunk/ruby-oci8/ChangeLog
===================================================================
--- trunk/ruby-oci8/ChangeLog	2012-04-21 12:03:15 UTC (rev 510)
+++ trunk/ruby-oci8/ChangeLog	2012-04-22 09:56:15 UTC (rev 511)
@@ -1,3 +1,13 @@
+2012-04-22  KUBO Takehiro  <kubo at jiubao.org>
+	* NEWS: add changes between 2.1.0 and 2.1.1.
+	* README -> README.md: renamed.
+	* .yardopts: added for yard.
+	* docs/install-binary-package.md, docs/report-installation-issue.md:
+	    added.
+	* docs/platform-specific-issues.md, lib/oci8/bindtype.rb, lib/oci8/connection_pool.rb
+	  lib/oci8/object.rb, lib/oci8/properties.rb: fix documents.
+	* ruby-oci8.gemspec, dist-files: fix for renamed and added files.
+
 2012-04-21  KUBO Takehiro  <kubo at jiubao.org>
 	* test/test_datetime.rb: fix to pass tests on ruby 1.9.1 and earlier.
 

Modified: trunk/ruby-oci8/NEWS
===================================================================
--- trunk/ruby-oci8/NEWS	2012-04-21 12:03:15 UTC (rev 510)
+++ trunk/ruby-oci8/NEWS	2012-04-22 09:56:15 UTC (rev 511)
@@ -1,5 +1,51 @@
 # @markup markdown
 
+2.1.1
+=====
+
+New Features
+------------
+
+### Statement caching in OCI
+
+See {http://docs.oracle.com/cd/E11882_01/appdev.112/e10646/oci09adv.htm#i471377}.
+This feature is enabled only when the Oracle client is 9iR2 or upper.
+
+The default cache size is 20. It can be changed as follows.
+
+    # change the size to 100.
+    OCI8.properties[:statement_cache_size] = 100
+
+Specification changes
+---------------------
+
+### OCI8::LOB#read() returns an empty string '' when it is an empty lob.
+
+It had been returned nil.
+
+Fixed Issues
+------------
+
+-   OCI8::CLOB.new(conn, '') works now.
+
+-   fix core dump when calling PL/SQL procedure with cursor argument.
+    See: {https://github.com/kubo/ruby-oci8/issues/11}
+
+    (reported by Raimonds Simanovskis)
+
+-   fix testcase failures in DST.
+    See: {https://github.com/kubo/ruby-oci8/issues/8}
+
+    (reported by Yasuo Honda)
+
+-   fix a compilation issue on Redhat.
+
+    (reported by John Beckwith and others)
+
+-   fix "wrong number of arguments (1 for 2)" when a date member in a object type is accessed.
+
+    (repored by Leo? Bitto)
+
 2.1.0
 =====
 

Deleted: trunk/ruby-oci8/README
===================================================================
--- trunk/ruby-oci8/README	2012-04-21 12:03:15 UTC (rev 510)
+++ trunk/ruby-oci8/README	2012-04-22 09:56:15 UTC (rev 511)
@@ -1,5 +0,0 @@
-Ruby-oci8 is a ruby interface for Oracle using OCI8 API. 
-The latest version (2.1.x) works with Oracle9i or later.
-Use ruby-oci8 2.0.6 or earlier for Oracle 8.
-
-See: http://ruby-oci8.rubyforge.org

Copied: trunk/ruby-oci8/README.md (from rev 497, trunk/ruby-oci8/README)
===================================================================
--- trunk/ruby-oci8/README.md	                        (rev 0)
+++ trunk/ruby-oci8/README.md	2012-04-22 09:56:15 UTC (rev 511)
@@ -0,0 +1,36 @@
+# @markup markdown
+
+What is ruby-oci8
+=================
+
+Ruby-oci8 is a ruby interface for Oracle Database. The latest version
+is available for all Oracle versions after Oracle 9i including Oracle
+Instant Client.
+
+If you need to use Oracle 8, use ruby-oci8 2.0.6.
+
+As for Oracle7, use Oracle7 Module for Ruby by Yoshida Masato.
+
+What's new
+==========
+
+See {file:NEWS}.
+
+Sample one-liner
+================
+
+Connect to scott/tiger, select `emp` and print as CSV format.
+
+    ruby -r oci8 -e "OCI8.new('scott', 'tiger').exec('select * from emp') do |r| puts r.join(','); end"
+
+If you install a ruby-oci8 gem package, you may need to add `-rubygems` before `-r oci8`.
+
+Installation
+============
+
+Look at the followings:
+
+* {file:docs/install-full-client.md}
+* {file:docs/install-instant-client.md}
+* {file:docs/install-binary-package.md}
+

Modified: trunk/ruby-oci8/dist-files
===================================================================
--- trunk/ruby-oci8/dist-files	2012-04-21 12:03:15 UTC (rev 510)
+++ trunk/ruby-oci8/dist-files	2012-04-22 09:56:15 UTC (rev 511)
@@ -1,16 +1,18 @@
 ChangeLog
 Makefile
 NEWS
-README
+README.md
 VERSION
 dist-files
 metaconfig
 pre-distclean.rb
 ruby-oci8.gemspec
 setup.rb
+docs/install-binary-package.md
 docs/install-full-client.md
 docs/install-instant-client.md
 docs/platform-specific-issues.md
+docs/report-installation-issue.md
 ext/oci8/.document
 ext/oci8/MANIFEST
 ext/oci8/apiwrap.c.tmpl

Added: trunk/ruby-oci8/docs/install-binary-package.md
===================================================================
--- trunk/ruby-oci8/docs/install-binary-package.md	                        (rev 0)
+++ trunk/ruby-oci8/docs/install-binary-package.md	2012-04-22 09:56:15 UTC (rev 511)
@@ -0,0 +1,40 @@
+# @title Install Binary Package
+
+Windows 32-bit (mingw32 ruby)
+=============================
+
+Run the following command:
+
+    gem install ruby-oci8
+
+Windows 32-bit (mswin32 ruby)
+=============================
+
+Run the following command:
+
+    gem install --platform x86-mingw32 ruby-oci8
+
+Ruby-oci8 gem for x86-mingw32 works on mswin32 ruby.
+If it doesn't work, see {file:docs/install-instant-client.md} or {file:docs/install-full-client.md}.
+
+Other platforms
+===============
+
+We doesn't make binary gems for other platforms.
+If you need to distribute a binary gem, compile ruby-oci8 and run the following command.
+
+    gem build ruby-oci8.gemspec -- current
+
+Note that you need to compile it on the oldest versions of the platform you support
+and for the oldest versions of the Oracle databases.
+
+If you could not fix the Oracle versions, compile ruby-oci8 and make a gem as follows:
+
+    gzip -dc ruby-oci8-VERSION.tar.gz | tar xvf -
+    cd ruby-oci8-VERSION
+    ruby setup.rb config -- --with-runtime-check
+    make
+    gem build ruby-oci8.gemspec -- current
+
+When the option `--with-runtime-check` is set, ruby-oci8 checks the Oracle version
+and available OCI functions at runtime.

Modified: trunk/ruby-oci8/docs/platform-specific-issues.md
===================================================================
--- trunk/ruby-oci8/docs/platform-specific-issues.md	2012-04-21 12:03:15 UTC (rev 510)
+++ trunk/ruby-oci8/docs/platform-specific-issues.md	2012-04-22 09:56:15 UTC (rev 511)
@@ -8,12 +8,12 @@
 
 If the following error occurs even though libc6-dev is installed,
 
-  Do you install glibc-devel(redhat) or libc6-dev(debian)?
-  You need /usr/include/sys/types.h to compile ruby-oci8.
+    Do you install glibc-devel(redhat) or libc6-dev(debian)?
+    You need /usr/include/sys/types.h to compile ruby-oci8.
 
 You need to use ruby-oci8 2.1.0 or upper. Otherwise, run the following command and re-install ruby-oci8.
 
- $ sudo ln -s /usr/include/linux/ /usr/include/sys
+    $ sudo ln -s /usr/include/linux/ /usr/include/sys
 
 General Linux
 -------------
@@ -37,12 +37,13 @@
 OS X 10.7 Lion
 --------------
 
-64-bit instant client doesn't work. Use 32-bit instant client or jruby.
+64-bit instant client doesn't work. Use 32-bit ruby and instant client or jruby.
 
 See:
-* http://rubyforge.org/forum/forum.php?thread_id=49548&forum_id=1078
-* https://forums.oracle.com/forums/thread.jspa?threadID=2187558
 
+* {http://rubyforge.org/forum/forum.php?thread\_id=49548&forum\_id=1078}
+* {https://forums.oracle.com/forums/thread.jspa?threadID=2187558}
+
 Intel Mac (64-bit)
 ------------------
 

Added: trunk/ruby-oci8/docs/report-installation-issue.md
===================================================================
--- trunk/ruby-oci8/docs/report-installation-issue.md	                        (rev 0)
+++ trunk/ruby-oci8/docs/report-installation-issue.md	2012-04-22 09:56:15 UTC (rev 511)
@@ -0,0 +1,50 @@
+# @title Report Installation Issues
+
+Look at {file:docs/platform-specific-issues.md},
+[the issues page on github][github] and [the ruby-oci8 help forum on rubyforge][rubyforge]
+to check whether your issue is fixed or not.
+
+If it is a new one, post the following information to [github][] or [rubyforge][].
+
+[github]: https://github.com/kubo/ruby-oci8/issues
+[rubyforge]: http://rubyforge.org/forum/forum.php?forum_id=1078
+
+*    Messages printed out to the console
+
+*    `gem_make.out` if you install a gem
+
+*    Last 100 lines of 'ext/oci8/mkmf.log'
+
+     Get them as follows.
+
+         tail -100 ext/oci8/mkmf.log
+
+*    The results of the following commands:
+
+         file `which ruby`
+         ruby --version
+         ruby -r rbconfig -e "p Config::CONFIG['host']"
+         ruby -r rbconfig -e "p Config::CONFIG['CC']"
+         ruby -r rbconfig -e "p Config::CONFIG['CFLAGS']"
+         ruby -r rbconfig -e "p Config::CONFIG['LDSHARED']"
+         ruby -r rbconfig -e "p Config::CONFIG['LDFLAGS']"
+         ruby -r rbconfig -e "p Config::CONFIG['DLDLAGS']"
+         ruby -r rbconfig -e "p Config::CONFIG['LIBS']"
+         ruby -r rbconfig -e "p Config::CONFIG['GNU_LD']"
+         
+         # if you use gcc,
+         gcc --print-prog-name=ld
+         gcc --print-prog-name=as
+         
+         # Oracle full client
+         file $ORACLE_HOME/bin/oracle
+         
+         # Oracle Instant client. You need to change INSTANT_CLIENT_DIRECTORY.
+         file INSTANT_CLIENT_DIRECTORY/libclntsh.*
+         
+         echo $LD_LIBRARY_PATH
+         echo $LIBPATH              # AIX
+         echo $SHLIB_PATH           # HP-UX PA-RISC 32-bit ruby
+         echo $DYLD_LIBRARY_PATH    # Mac OS X
+         echo $LD_LIBRARY_PATH_32   # Solaris 32-bit ruby
+         echo $LD_LIBRARY_PATH_64   # Solaris 64-bit ruby

Modified: trunk/ruby-oci8/lib/oci8/bindtype.rb
===================================================================
--- trunk/ruby-oci8/lib/oci8/bindtype.rb	2012-04-21 12:03:15 UTC (rev 510)
+++ trunk/ruby-oci8/lib/oci8/bindtype.rb	2012-04-22 09:56:15 UTC (rev 511)
@@ -4,6 +4,7 @@
 # Copyright (C) 2009-2011 KUBO Takehiro <kubo at jiubao.org>
 #++
 
+#
 class OCI8
   module BindType
     Mapping = {}

Modified: trunk/ruby-oci8/lib/oci8/connection_pool.rb
===================================================================
--- trunk/ruby-oci8/lib/oci8/connection_pool.rb	2012-04-21 12:03:15 UTC (rev 510)
+++ trunk/ruby-oci8/lib/oci8/connection_pool.rb	2012-04-22 09:56:15 UTC (rev 511)
@@ -4,6 +4,7 @@
 # Copyright (C) 2010 KUBO Takehiro <kubo at jiubao.org>
 #++
 
+#
 class OCI8
 
   # Connection pooling is the use of a group (the pool) of reusable

Modified: trunk/ruby-oci8/lib/oci8/object.rb
===================================================================
--- trunk/ruby-oci8/lib/oci8/object.rb	2012-04-21 12:03:15 UTC (rev 510)
+++ trunk/ruby-oci8/lib/oci8/object.rb	2012-04-22 09:56:15 UTC (rev 511)
@@ -5,11 +5,17 @@
 
 class OCI8
 
+  # Returns the type descriptor object which correspond to the given class.
+  #
+  # @param [class of an OCI8::Object::Base's subclass]
+  # @return [OCI8::TDO]
+  #
+  # @private
   def get_tdo_by_class(klass)
     @id_to_tdo ||= {}
     @name_to_tdo ||= {}
     tdo = @name_to_tdo[klass.typename]
-    return tdo if tdo
+    return tdo if tdo # found in the cache.
 
     metadata = describe_any(klass.typename)
     if metadata.is_a? OCI8::Metadata::Synonym
@@ -21,6 +27,12 @@
     OCI8::TDO.new(self, metadata, klass)
   end
 
+  # Returns the type descriptor object which correspond to the given metadata.
+  #
+  # @param [OCI8::Metadata::Base's subclass]
+  # @return [OCI8::TDO]
+  #
+  # @private
   def get_tdo_by_metadata(metadata)
     @id_to_tdo ||= {}
     @name_to_tdo ||= {}
@@ -59,7 +71,10 @@
     OCI8::TDO.new(self, metadata, klass)
   end
 
-  class BindArgumentHelper # :nodoc:
+  # A helper class to bind arguments.
+  #
+  # @private
+  class BindArgumentHelper
     attr_reader :arg_str
     def initialize(*args)
       if args.length == 1 and args[0].is_a? Hash
@@ -102,12 +117,14 @@
       @@name_to_class = {}
       @@default_connection = nil
 
+      # @private
       def self.inherited(klass)
         name = klass.to_s.gsub(/^.*::/, '').gsub(/([a-z\d])([A-Z])/,'\1_\2').upcase
         @@class_to_name[klass] = name
         @@name_to_class[name] = klass
       end
 
+      # @private
       def self.get_class_by_typename(name)
         @@name_to_class[name]
       end
@@ -125,6 +142,7 @@
         @@name_to_class[name] = self
       end
 
+      # @deprecated
       def self.default_connection=(con)
         @@default_connection = con
       end
@@ -158,6 +176,8 @@
       end
 
       # class method
+
+      # @private
       def self.method_missing(method_id, *args)
         if args[0].is_a? OCI8
           con = args.shift
@@ -204,6 +224,8 @@
       end
 
       # instance method
+
+      # @private
       def method_missing(method_id, *args)
         if @attributes.is_a? Array
           return @attributes if method_id == :to_ary
@@ -283,13 +305,14 @@
     end # OCI8::Object::Base
   end # OCI8::Object
 
+  # @private
   class TDO
     # full-qualified object type name.
     #  e.g.
     #   MDSYS.SDO_GEOMETRY
     attr_reader :typename
 
-    # named_type
+    # a subclass of OCI8::Object::Base
     attr_reader :ruby_class
 
     attr_reader :val_size
@@ -495,6 +518,7 @@
     end
   end
 
+  # @private
   class NamedType
     def to_value
       return nil if self.null?
@@ -528,6 +552,7 @@
     end
   end
 
+  # @private
   class NamedCollection
     def to_value
       attr = self.attributes

Modified: trunk/ruby-oci8/lib/oci8/properties.rb
===================================================================
--- trunk/ruby-oci8/lib/oci8/properties.rb	2012-04-21 12:03:15 UTC (rev 510)
+++ trunk/ruby-oci8/lib/oci8/properties.rb	2012-04-22 09:56:15 UTC (rev 511)
@@ -2,6 +2,7 @@
 #
 # Copyright (C) 2010-2011 KUBO Takehiro <kubo at jiubao.org>
 
+#
 class OCI8
 
   @@properties = {

Modified: trunk/ruby-oci8/ruby-oci8.gemspec
===================================================================
--- trunk/ruby-oci8/ruby-oci8.gemspec	2012-04-21 12:03:15 UTC (rev 510)
+++ trunk/ruby-oci8/ruby-oci8.gemspec	2012-04-22 09:56:15 UTC (rev 511)
@@ -31,7 +31,7 @@
   s.description = <<EOS
 ruby-oci8 is a ruby interface for Oracle using OCI8 API. It is available with Oracle8, Oracle8i, Oracle9i, Oracle10g and Oracle Instant Client.
 EOS
-  s.has_rdoc = true
+  s.has_rdoc = 'yard'
   s.authors = ['KUBO Takehiro']
   s.platform = gem_platform
   files = File.read('dist-files').split("\n")
@@ -67,8 +67,8 @@
     end
     files << 'lib/oci8.rb'
   end
+  s.require_paths = ['lib', 'ext/oci8']
   s.files = files
   s.test_files = 'test/test_all.rb'
-  s.rdoc_options = ['--main', 'README']
-  s.extra_rdoc_files = ['README']
+  s.extra_rdoc_files = ['README.md']
 end


From nobody at rubyforge.org  Sun Apr 22 09:58:36 2012
From: nobody at rubyforge.org (nobody at rubyforge.org)
Date: Sun, 22 Apr 2012 09:58:36 +0000 (UTC)
Subject: [ruby-oci8-commit] [512] trunk/ruby-oci8: fix ignore files.
Message-ID: <20120422095836.B006A263041@rubyforge.org>

Revision: 512
Author:   kubo
Date:     2012-04-22 09:58:36 +0000 (Sun, 22 Apr 2012)
Log Message:
-----------
fix ignore files.

Modified Paths:
--------------
    trunk/ruby-oci8/.gitignore

Property Changed:
----------------
    trunk/ruby-oci8/
    trunk/ruby-oci8/ext/oci8/
    trunk/ruby-oci8/lib/


Property changes on: trunk/ruby-oci8
___________________________________________________________________
Modified: svn:ignore
   - config.save
sqlnet.log
*.rbc
.git
doc
.yardoc

   + config.save
sqlnet.log
*.gem
*.rbc
.git
doc
.yardoc


Modified: trunk/ruby-oci8/.gitignore
===================================================================
--- trunk/ruby-oci8/.gitignore	2012-04-22 09:56:15 UTC (rev 511)
+++ trunk/ruby-oci8/.gitignore	2012-04-22 09:58:36 UTC (rev 512)
@@ -1,3 +1,5 @@
+*.gem
+*~
 .svn
 .yardoc
 config.save
@@ -5,19 +7,24 @@
 docs/.svn
 ext/.svn
 ext/oci8/.svn
+ext/oci8/Makefile
+ext/oci8/OCI.def
 ext/oci8/apiwrap.h
-ext/oci8/Makefile
 ext/oci8/apiwrap.c
 ext/oci8/depend
 ext/oci8/extconf.h
 ext/oci8/mkmf.log
+ext/oci8/oci8lib_*.def
 ext/oci8/*.def
+ext/oci8/*.map
 ext/oci8/*.o
 ext/oci8/*.so
 ext/oci8/*.obj
 ext/oci8/*~
 lib/oci8.rb
+lib/*.map
 lib/*.rbc
+lib/*.so
 lib/*~
 lib/oci8/*.rbc
 lib/oci8/*~


Property changes on: trunk/ruby-oci8/ext/oci8
___________________________________________________________________
Modified: svn:ignore
   - Makefile
mkmf.log
extconf.h
depend
oci8lib.so
apiwrap.c
apiwrap.h
*.rbc

   + Makefile
OCI.def
mkmf.log
extconf.h
depend
oci8lib.so
apiwrap.c
apiwrap.h
oci8lib_*.def
*.map
*.rbc



Property changes on: trunk/ruby-oci8/lib
___________________________________________________________________
Modified: svn:ignore
   - oci8.rb
*.rbc

   + oci8.rb
*.rbc
*.map



From nobody at rubyforge.org  Sun Apr 22 11:12:56 2012
From: nobody at rubyforge.org (nobody at rubyforge.org)
Date: Sun, 22 Apr 2012 11:12:56 +0000 (UTC)
Subject: [ruby-oci8-commit] [513] trunk/ruby-oci8: update to 2.1.1.
Message-ID: <20120422111256.D072B263042@rubyforge.org>

Revision: 513
Author:   kubo
Date:     2012-04-22 11:12:56 +0000 (Sun, 22 Apr 2012)
Log Message:
-----------
update to 2.1.1.

Modified Paths:
--------------
    trunk/ruby-oci8/ChangeLog
    trunk/ruby-oci8/README.md
    trunk/ruby-oci8/VERSION

Modified: trunk/ruby-oci8/ChangeLog
===================================================================
--- trunk/ruby-oci8/ChangeLog	2012-04-22 09:58:36 UTC (rev 512)
+++ trunk/ruby-oci8/ChangeLog	2012-04-22 11:12:56 UTC (rev 513)
@@ -1,4 +1,8 @@
 2012-04-22  KUBO Takehiro  <kubo at jiubao.org>
+	* VERSION: update to 2.1.1.
+	* README.md: add links.
+
+2012-04-22  KUBO Takehiro  <kubo at jiubao.org>
 	* NEWS: add changes between 2.1.0 and 2.1.1.
 	* README -> README.md: renamed.
 	* .yardopts: added for yard.

Modified: trunk/ruby-oci8/README.md
===================================================================
--- trunk/ruby-oci8/README.md	2012-04-22 09:58:36 UTC (rev 512)
+++ trunk/ruby-oci8/README.md	2012-04-22 11:12:56 UTC (rev 513)
@@ -1,5 +1,3 @@
-# @markup markdown
-
 What is ruby-oci8
 =================
 
@@ -28,9 +26,13 @@
 Installation
 ============
 
-Look at the followings:
-
 * {file:docs/install-full-client.md}
 * {file:docs/install-instant-client.md}
 * {file:docs/install-binary-package.md}
 
+Report issues
+=============
+
+* {file:docs/report-installation-issue.md}
+* [The issues page on github](https://github.com/kubo/ruby-oci8/issues)
+* [The ruby-oci8 help forum on rubyforge](http://rubyforge.org/forum/forum.php?forum_id=1078)

Modified: trunk/ruby-oci8/VERSION
===================================================================
--- trunk/ruby-oci8/VERSION	2012-04-22 09:58:36 UTC (rev 512)
+++ trunk/ruby-oci8/VERSION	2012-04-22 11:12:56 UTC (rev 513)
@@ -1 +1 @@
-2.1.0
+2.1.1


From nobody at rubyforge.org  Sun Apr 22 11:28:25 2012
From: nobody at rubyforge.org (nobody at rubyforge.org)
Date: Sun, 22 Apr 2012 11:28:25 +0000 (UTC)
Subject: [ruby-oci8-commit] [514] trunk/ruby-oci8/dist-files:
Message-ID: <20120422112825.62FBA263042@rubyforge.org>

Revision: 514
Author:   kubo
Date:     2012-04-22 11:28:25 +0000 (Sun, 22 Apr 2012)
Log Message:
-----------


Modified Paths:
--------------
    trunk/ruby-oci8/dist-files

Modified: trunk/ruby-oci8/dist-files
===================================================================
--- trunk/ruby-oci8/dist-files	2012-04-22 11:12:56 UTC (rev 513)
+++ trunk/ruby-oci8/dist-files	2012-04-22 11:28:25 UTC (rev 514)
@@ -1,3 +1,4 @@
+.yardopts
 ChangeLog
 Makefile
 NEWS


From nobody at rubyforge.org  Sun Apr 22 11:52:10 2012
From: nobody at rubyforge.org (nobody at rubyforge.org)
Date: Sun, 22 Apr 2012 11:52:10 +0000 (UTC)
Subject: [ruby-oci8-commit] [515] tags/ruby-oci8-2.1.1/: tag 2.1.1
Message-ID: <20120422115210.E9EB7263042@rubyforge.org>

Revision: 515
Author:   kubo
Date:     2012-04-22 11:52:10 +0000 (Sun, 22 Apr 2012)
Log Message:
-----------
tag 2.1.1

Added Paths:
-----------
    tags/ruby-oci8-2.1.1/


From nobody at rubyforge.org  Tue Apr 24 12:46:35 2012
From: nobody at rubyforge.org (nobody at rubyforge.org)
Date: Tue, 24 Apr 2012 12:46:35 +0000 (UTC)
Subject: [ruby-oci8-commit] [516] trunk/ruby-oci8: fix internal heap error
	in OCI.
Message-ID: <20120424124635.B68AA3AFF8@rubyforge.org>

Revision: 516
Author:   kubo
Date:     2012-04-24 12:46:35 +0000 (Tue, 24 Apr 2012)
Log Message:
-----------
fix internal heap error in OCI.
(github issue #12 reported by Yasuo Honda)

Modified Paths:
--------------
    trunk/ruby-oci8/ChangeLog
    trunk/ruby-oci8/ext/oci8/metadata.c

Modified: trunk/ruby-oci8/ChangeLog
===================================================================
--- trunk/ruby-oci8/ChangeLog	2012-04-22 11:52:10 UTC (rev 515)
+++ trunk/ruby-oci8/ChangeLog	2012-04-24 12:46:35 UTC (rev 516)
@@ -1,3 +1,7 @@
+2012-04-24  KUBO Takehiro  <kubo at jiubao.org>
+	* ext/oci8/metadata.c: fix internal heap error in OCI.
+	    (github issue #12 reported by Yasuo Honda)
+
 2012-04-22  KUBO Takehiro  <kubo at jiubao.org>
 	* VERSION: update to 2.1.1.
 	* README.md: add links.

Modified: trunk/ruby-oci8/ext/oci8/metadata.c
===================================================================
--- trunk/ruby-oci8/ext/oci8/metadata.c	2012-04-22 11:52:10 UTC (rev 515)
+++ trunk/ruby-oci8/ext/oci8/metadata.c	2012-04-24 12:46:35 UTC (rev 516)
@@ -29,6 +29,11 @@
     rb_gc_mark(md->svc);
 }
 
+static void oci8_metadata_free(oci8_base_t *base)
+{
+    base->type = 0; /* to prevent OCIDescriptorFree */
+}
+
 VALUE oci8_metadata_create(OCIParam *parmhp, VALUE svc, VALUE parent)
 {
     oci8_metadata_t *md;
@@ -199,7 +204,7 @@
 
 oci8_base_vtable_t oci8_metadata_vtable = {
     oci8_metadata_mark,
-    NULL,
+    oci8_metadata_free,
     sizeof(oci8_metadata_t),
 };
 


From nobody at rubyforge.org  Sat Apr 28 06:54:14 2012
From: nobody at rubyforge.org (nobody at rubyforge.org)
Date: Sat, 28 Apr 2012 06:54:14 +0000 (UTC)
Subject: [ruby-oci8-commit] [517] trunk/ruby-oci8: delete code which
 overwrites signal handlers registered by ruby.
Message-ID: <20120428065414.9AF25263041@rubyforge.org>

Revision: 517
Author:   kubo
Date:     2012-04-28 06:54:14 +0000 (Sat, 28 Apr 2012)
Log Message:
-----------
delete code which overwrites signal handlers registered by ruby.

Modified Paths:
--------------
    trunk/ruby-oci8/ChangeLog
    trunk/ruby-oci8/ext/oci8/oci8lib.c

Modified: trunk/ruby-oci8/ChangeLog
===================================================================
--- trunk/ruby-oci8/ChangeLog	2012-04-24 12:46:35 UTC (rev 516)
+++ trunk/ruby-oci8/ChangeLog	2012-04-28 06:54:14 UTC (rev 517)
@@ -1,3 +1,8 @@
+2012-04-28  KUBO Takehiro  <kubo at jiubao.org>
+	* ext/oci8/oci8lib.c: delete code which overwrites signal handlers
+	    registered by ruby. This was committed by mistake.
+	    See: http://rubyforge.org/forum/forum.php?thread_id=50690&forum_id=1078
+
 2012-04-24  KUBO Takehiro  <kubo at jiubao.org>
 	* ext/oci8/metadata.c: fix internal heap error in OCI.
 	    (github issue #12 reported by Yasuo Honda)

Modified: trunk/ruby-oci8/ext/oci8/oci8lib.c
===================================================================
--- trunk/ruby-oci8/ext/oci8/oci8lib.c	2012-04-24 12:46:35 UTC (rev 516)
+++ trunk/ruby-oci8/ext/oci8/oci8lib.c	2012-04-28 06:54:14 UTC (rev 517)
@@ -1,15 +1,10 @@
 /* -*- c-file-style: "ruby"; indent-tabs-mode: nil -*- */
 /*
- * Copyright (C) 2002-2011 KUBO Takehiro <kubo at jiubao.org>
+ * Copyright (C) 2002-2012 KUBO Takehiro <kubo at jiubao.org>
  */
 
 #include "oci8.h"
 
-#define DEBUG_CORE_FILE 1
-#ifdef DEBUG_CORE_FILE
-#include <signal.h>
-#endif
-
 ID oci8_id_at_last_error;
 ID oci8_id_new;
 ID oci8_id_get;
@@ -145,10 +140,6 @@
 #ifdef USE_WIN32_C
     Init_oci8_win32(cOCI8);
 #endif
-
-#ifdef DEBUG_CORE_FILE
-    signal(SIGSEGV, SIG_DFL);
-#endif
 }
 
 VALUE oci8_define_class(const char *name, oci8_base_vtable_t *vptr)


From nobody at rubyforge.org  Sat Apr 28 07:01:23 2012
From: nobody at rubyforge.org (nobody at rubyforge.org)
Date: Sat, 28 Apr 2012 07:01:23 +0000 (UTC)
Subject: [ruby-oci8-commit] [518] trunk/ruby-oci8: disable statement caching
	by default.
Message-ID: <20120428070123.9B599263041@rubyforge.org>

Revision: 518
Author:   kubo
Date:     2012-04-28 07:01:23 +0000 (Sat, 28 Apr 2012)
Log Message:
-----------
disable statement caching by default.
This is workaround about a SIGSEGV issue.
See: https://github.com/rsim/oracle-enhanced/issues/162

Modified Paths:
--------------
    trunk/ruby-oci8/ChangeLog
    trunk/ruby-oci8/lib/oci8/oci8.rb
    trunk/ruby-oci8/lib/oci8/properties.rb

Modified: trunk/ruby-oci8/ChangeLog
===================================================================
--- trunk/ruby-oci8/ChangeLog	2012-04-28 06:54:14 UTC (rev 517)
+++ trunk/ruby-oci8/ChangeLog	2012-04-28 07:01:23 UTC (rev 518)
@@ -1,4 +1,9 @@
 2012-04-28  KUBO Takehiro  <kubo at jiubao.org>
+	* lib/oci8/oci8.rb, lib/oci8/properties.rb: disable statement caching by default.
+	    This is workaround about a SIGSEGV issue.
+	    See: https://github.com/rsim/oracle-enhanced/issues/162
+
+2012-04-28  KUBO Takehiro  <kubo at jiubao.org>
 	* ext/oci8/oci8lib.c: delete code which overwrites signal handlers
 	    registered by ruby. This was committed by mistake.
 	    See: http://rubyforge.org/forum/forum.php?thread_id=50690&forum_id=1078

Modified: trunk/ruby-oci8/lib/oci8/oci8.rb
===================================================================
--- trunk/ruby-oci8/lib/oci8/oci8.rb	2012-04-28 06:54:14 UTC (rev 517)
+++ trunk/ruby-oci8/lib/oci8/oci8.rb	2012-04-28 07:01:23 UTC (rev 518)
@@ -119,6 +119,7 @@
     end
 
     stmt_cache_size = OCI8.properties[:statement_cache_size]
+    stmt_cache_size = nil if stmt_cache_size == 0
 
     if mode.nil? and cred.nil?
       # logon by the OCI function OCILogon2().

Modified: trunk/ruby-oci8/lib/oci8/properties.rb
===================================================================
--- trunk/ruby-oci8/lib/oci8/properties.rb	2012-04-28 06:54:14 UTC (rev 517)
+++ trunk/ruby-oci8/lib/oci8/properties.rb	2012-04-28 07:01:23 UTC (rev 518)
@@ -1,6 +1,6 @@
 # properties.rb -- implements OCI8.properties
 #
-# Copyright (C) 2010-2011 KUBO Takehiro <kubo at jiubao.org>
+# Copyright (C) 2010-2012 KUBO Takehiro <kubo at jiubao.org>
 
 #
 class OCI8
@@ -9,7 +9,7 @@
     :length_semantics => :byte,
     :bind_string_as_nchar => false,
     :float_conversion_type => :ruby,
-    :statement_cache_size => 20,
+    :statement_cache_size => 0,
   }
 
   if OCI8.oracle_client_version < OCI8::ORAVER_9_2
@@ -89,7 +89,8 @@
   # [:statement_cache_size]
   #     (new in 2.1.1)
   #     
-  #     The statement cache size per each session. The default value is 20 statements.
+  #     The statement cache size per each session. The default size is 0, which
+  #     means no statement cache, since 2.1.2. It was 20 in 2.1.1.
   #     This feature is available on Oracle 9iR2 or later.
   #     See: http://docs.oracle.com/cd/E11882_01/appdev.112/e10646/oci09adv.htm#i471377
   #


From nobody at rubyforge.org  Sat Apr 28 07:16:47 2012
From: nobody at rubyforge.org (nobody at rubyforge.org)
Date: Sat, 28 Apr 2012 07:16:47 +0000 (UTC)
Subject: [ruby-oci8-commit] [519] trunk/ruby-oci8: Update to 2.1.2
Message-ID: <20120428071647.E761B3AFF4@rubyforge.org>

Revision: 519
Author:   kubo
Date:     2012-04-28 07:16:47 +0000 (Sat, 28 Apr 2012)
Log Message:
-----------
Update to 2.1.2

Modified Paths:
--------------
    trunk/ruby-oci8/ChangeLog
    trunk/ruby-oci8/NEWS
    trunk/ruby-oci8/VERSION

Modified: trunk/ruby-oci8/ChangeLog
===================================================================
--- trunk/ruby-oci8/ChangeLog	2012-04-28 07:01:23 UTC (rev 518)
+++ trunk/ruby-oci8/ChangeLog	2012-04-28 07:16:47 UTC (rev 519)
@@ -1,4 +1,8 @@
 2012-04-28  KUBO Takehiro  <kubo at jiubao.org>
+	* NEWS: add changes between 2.1.2 and 2.1.1
+	* VERSION: change the version to 2.1.2.
+
+2012-04-28  KUBO Takehiro  <kubo at jiubao.org>
 	* lib/oci8/oci8.rb, lib/oci8/properties.rb: disable statement caching by default.
 	    This is workaround about a SIGSEGV issue.
 	    See: https://github.com/rsim/oracle-enhanced/issues/162

Modified: trunk/ruby-oci8/NEWS
===================================================================
--- trunk/ruby-oci8/NEWS	2012-04-28 07:01:23 UTC (rev 518)
+++ trunk/ruby-oci8/NEWS	2012-04-28 07:16:47 UTC (rev 519)
@@ -1,5 +1,26 @@
 # @markup markdown
 
+2.1.2
+=====
+
+Specification changes
+---------------------
+
+### Statement caching in OCI is disabled by default.
+
+This is workaround about a SIGSEGV issue.
+See: [oracle enhanced issue #162](https://github.com/rsim/oracle-enhanced/issues/162)
+Fixed Issues
+------------
+
+-   delete code which overwrites signal handlers registered by ruby.
+    See: [rubyforge thread 50690](http://rubyforge.org/forum/forum.php?thread_id=50690&forum_id=1078)
+
+-   fix internal heap error in OCI.
+    See: [github issue #12](https://github.com/kubo/ruby-oci8/issues/12)
+
+    (reported by Yasuo Honda)
+
 2.1.1
 =====
 
@@ -16,6 +37,8 @@
     # change the size to 100.
     OCI8.properties[:statement_cache_size] = 100
 
+Note: The default size was changed to zero in 2.1.2.
+
 Specification changes
 ---------------------
 

Modified: trunk/ruby-oci8/VERSION
===================================================================
--- trunk/ruby-oci8/VERSION	2012-04-28 07:01:23 UTC (rev 518)
+++ trunk/ruby-oci8/VERSION	2012-04-28 07:16:47 UTC (rev 519)
@@ -1 +1 @@
-2.1.1
+2.1.2