[ruby-oci8-commit] [502] trunk/ruby-oci8: revise rdoc comments.

nobody at rubyforge.org nobody at rubyforge.org
Sun Apr 8 11:32:56 UTC 2012


Revision: 502
Author:   kubo
Date:     2012-04-08 11:32:55 +0000 (Sun, 08 Apr 2012)
Log Message:
-----------
revise rdoc comments.

Modified Paths:
--------------
    trunk/ruby-oci8/ChangeLog
    trunk/ruby-oci8/ext/oci8/lob.c
    trunk/ruby-oci8/ext/oci8/win32.c
    trunk/ruby-oci8/lib/oci8/oracle_version.rb

Modified: trunk/ruby-oci8/ChangeLog
===================================================================
--- trunk/ruby-oci8/ChangeLog	2012-04-06 12:26:57 UTC (rev 501)
+++ trunk/ruby-oci8/ChangeLog	2012-04-08 11:32:55 UTC (rev 502)
@@ -1,3 +1,7 @@
+2012-04-08  KUBO Takehiro  <kubo at jiubao.org>
+	* ext/oci8/lob.c, ext/oci8/win32.c, lib/oci8/oracle_version.rb:
+	    revise rdoc comments.
+
 2012-04-06  KUBO Takehiro  <kubo at jiubao.org>
 	* ext/oci8/error.c, ext/oci8/ocihandle.c, ext/oci8/oradate.c,
 	  lib/oci8/encoding-init.rb, lib/oci8/oci8.rb, lib/oci8/ocihandle.rb:

Modified: trunk/ruby-oci8/ext/oci8/lob.c
===================================================================
--- trunk/ruby-oci8/ext/oci8/lob.c	2012-04-06 12:26:57 UTC (rev 501)
+++ trunk/ruby-oci8/ext/oci8/lob.c	2012-04-08 11:32:55 UTC (rev 502)
@@ -163,6 +163,41 @@
     }
 }
 
+/*
+ *  Document-class: OCI8::LOB
+ *
+ *  This is the abstract base class of large-object data types; BFILE, BLOB, CLOB and NCLOB.
+ *
+ */
+
+/*
+ *  Document-class: OCI8::CLOB
+ *
+ */
+
+/*
+ *  Document-class: OCI8::NCLOB
+ *
+ */
+
+/*
+ *  Document-class: OCI8::BLOB
+ *
+ */
+
+/*
+ *  Document-class: OCI8::BFILE
+ *
+ *  @method truncate(length)
+ *  @method size = length
+ *  @method write(data)
+ */
+
+/*
+ *  Closes the lob.
+ *
+ *  @return [self]
+ */
 static VALUE oci8_lob_close(VALUE self)
 {
     oci8_lob_t *lob = DATA_PTR(self);
@@ -203,24 +238,82 @@
     return Qnil;
 }
 
+/*
+ *  call-seq:
+ *    initialize(conn, contents = nil)
+ *
+ *  Creates a temporary CLOB when <i>contents</i> is not nil.
+ *  Otherwise, it creates an uninitialized lob, which is used internally
+ *  to fetch CLOB column data.
+ *
+ *  @example
+ *    # Inserts a file name and its contents as CLOB.
+ *    clob = OCI8::CLOB.new(conn, File.read(file_name))
+ *    conn.exec('insert into file_contents values (:1, :2)', file_name, clob)
+ *
+ *  @param [OCI8] conn connection
+ *  @param [String] contents
+ *  @return [OCI8::CLOB]
+ */
 static VALUE oci8_clob_initialize(int argc, VALUE *argv, VALUE self)
 {
     oci8_lob_do_initialize(argc, argv, self, SQLCS_IMPLICIT, OCI_TEMP_CLOB);
     return Qnil;
 }
 
+/*
+ *  call-seq:
+ *    initialize(conn, contents = nil)
+ *
+ *  Creates a temporary NCLOB when <i>contents</i> is not nil.
+ *  Otherwise, it creates an uninitialized lob, which is used internally
+ *  to fetch NCLOB column data.
+ *
+ *  @example
+ *    # Inserts a file name and its contents as NCLOB.
+ *    clob = OCI8::NCLOB.new(conn, File.read(file_name))
+ *    conn.exec('insert into file_contents values (:1, :2)', file_name, clob)
+ *
+ *  @param [OCI8] conn
+ *  @param [String] contents
+ *  @return [OCI8::NCLOB]
+ */
 static VALUE oci8_nclob_initialize(int argc, VALUE *argv, VALUE self)
 {
     oci8_lob_do_initialize(argc, argv, self, SQLCS_NCHAR, OCI_TEMP_CLOB);
     return Qnil;
 }
 
+/*
+ *  call-seq:
+ *    initialize(conn, contents = nil)
+ *
+ *  Creates a temporary BLOB when <i>contents</i> is not nil.
+ *  Otherwise, it creates an uninitialized lob, which is used internally
+ *  to fetch BLOB column data.
+ *
+ *  @example
+ *    # Inserts a file name and its contents as BLOB.
+ *    clob = OCI8::BLOB.new(conn, File.read(file_name, :mode => 'rb'))
+ *    conn.exec('insert into file_contents values (:1, :2)', file_name, clob)
+ *
+ *  @param [OCI8] conn
+ *  @param [String] contents
+ *  @return [OCI8::BLOB]
+ */
 static VALUE oci8_blob_initialize(int argc, VALUE *argv, VALUE self)
 {
     oci8_lob_do_initialize(argc, argv, self, SQLCS_IMPLICIT, OCI_TEMP_BLOB);
     return Qnil;
 }
 
+/*
+ *  call-seq:
+ *    __char_width = size
+ *
+ *  @private
+ *  IMO, nobody need and use this.
+ */
 static VALUE oci8_lob_set_char_width(VALUE self, VALUE vsize)
 {
     oci8_lob_t *lob = DATA_PTR(self);
@@ -234,6 +327,11 @@
     return vsize;
 }
 
+/*
+ *  Returns +true+ when <i>self</i> is initialized.
+ *
+ *  @return [true or false]
+ */
 static VALUE oci8_lob_available_p(VALUE self)
 {
     oci8_lob_t *lob = DATA_PTR(self);
@@ -244,17 +342,36 @@
     return is_initialized ? Qtrue : Qfalse;
 }
 
+/*
+ *  Returns the size.
+ *  For CLOB and NCLOB it is the number of characters,
+ *  for BLOB and BFILE it is the number of bytes.
+ *
+ *  @return [Integer]
+ */
 static VALUE oci8_lob_get_size(VALUE self)
 {
     return UB4_TO_NUM(oci8_lob_get_length(DATA_PTR(self)));
 }
 
+/*
+ *  Returns the current offset.
+ *  For CLOB and NCLOB it is the number of characters,
+ *  for BLOB and BFILE it is the number of bytes.
+ *
+ *  @return [Integer]
+ */
 static VALUE oci8_lob_get_pos(VALUE self)
 {
     oci8_lob_t *lob = DATA_PTR(self);
     return UB4_TO_NUM(lob->pos);
 }
 
+/*
+ *  Returns true if the current offset is at end of lob.
+ *
+ *  @return [true or false]
+ */
 static VALUE oci8_lob_eof_p(VALUE self)
 {
     oci8_lob_t *lob = DATA_PTR(self);
@@ -264,6 +381,20 @@
         return Qtrue;
 }
 
+/*
+ *  call-seq:
+ *     seek(amount, whence=IO::SEEK_SET)
+ *
+ *  Seeks to the given offset in the stream. The new position, measured in characters,
+ *  is obtained by adding offset <i>amount</i> to the position specified by <i>whence</i>.
+ *  If <i>whence</i> is set to IO::SEEK_SET, IO::SEEK_CUR, or IO::SEEK_END,
+ *  the offset is relative to the start of the file, the current position
+ *  indicator, or end-of-file, respectively.
+ *
+ *  @param [Integer] amount
+ *  @param [IO::SEEK_SET, IO::SEEK_CUR or IO::SEEK_END] whence
+ *  @return [self]
+ */
 static VALUE oci8_lob_seek(int argc, VALUE *argv, VALUE self)
 {
     oci8_lob_t *lob = DATA_PTR(self);
@@ -288,6 +419,11 @@
     return self;
 }
 
+/*
+ *  Sets the current offset at the beginning.
+ *
+ *  @return [true or false]
+ */
 static VALUE oci8_lob_rewind(VALUE self)
 {
     oci8_lob_t *lob = DATA_PTR(self);
@@ -295,6 +431,15 @@
     return self;
 }
 
+/*
+ *  call-seq:
+ *    truncate(length)
+ *
+ *  Changes the lob size to the given <i>length</i>.
+ *
+ *  @param [Integer] length
+ *  @return [self]
+ */
 static VALUE oci8_lob_truncate(VALUE self, VALUE len)
 {
     oci8_lob_t *lob = DATA_PTR(self);
@@ -306,12 +451,32 @@
     return self;
 }
 
+/*
+ *  call-seq:
+ *    size = length
+ *
+ *  Changes the lob size to the given <i>length</i>.
+ *
+ *  @param [Integer] length
+ *  @return [Integer]
+ */
 static VALUE oci8_lob_set_size(VALUE self, VALUE len)
 {
     oci8_lob_truncate(self, len);
     return len;
 }
 
+/*
+ *  call-seq:
+ *    read(length = nil)
+ *
+ *  Reads <i>length</i> characters for CLOB and NCLOB or <i>length</i>
+ *  bytes for BLOB and BILF from the current position.
+ *  When <i>length</i> is nil, it reads data until EOF.
+ *
+ *  @param [Integer] length
+ *  @return [String]
+ */
 static VALUE oci8_lob_read(int argc, VALUE *argv, VALUE self)
 {
     oci8_lob_t *lob = DATA_PTR(self);
@@ -412,6 +577,15 @@
     }
 }
 
+/*
+ *  call-seq:
+ *    write(data)
+ *
+ *  Writes <i>data</i>.
+ *
+ *  @param [String] data
+ *  @return [Integer]
+ */
 static VALUE oci8_lob_write(VALUE self, VALUE data)
 {
     oci8_lob_t *lob = DATA_PTR(self);
@@ -433,12 +607,20 @@
     return UINT2NUM(amt);
 }
 
+/*
+ *  @deprecated I'm not sure that this is what the name indicates.
+ *  @private
+ */
 static VALUE oci8_lob_get_sync(VALUE self)
 {
     oci8_lob_t *lob = DATA_PTR(self);
     return (lob->state == S_NO_OPEN_CLOSE) ? Qtrue : Qfalse;
 }
 
+/*
+ *  @deprecated I'm not sure that this is what the name indicates.
+ *  @private
+ */
 static VALUE oci8_lob_set_sync(VALUE self, VALUE b)
 {
     oci8_lob_t *lob = DATA_PTR(self);
@@ -452,6 +634,10 @@
     return b;
 }
 
+/*
+ *  @deprecated I'm not sure that this is what the name indicates.
+ *  @private
+ */
 static VALUE oci8_lob_flush(VALUE self)
 {
     oci8_lob_t *lob = DATA_PTR(self);
@@ -459,6 +645,12 @@
     return self;
 }
 
+/*
+ *  Returns the chunk size of a LOB.
+ *
+ *  @see http://docs.oracle.com/cd/E16338_01/appdev.112/e10646/oci17msc002.htm#i493090
+ *  @return [Integer]
+ */
 static VALUE oci8_lob_get_chunk_size(VALUE self)
 {
     oci8_lob_t *lob = DATA_PTR(self);
@@ -544,6 +736,19 @@
            &lob->base);
 }
 
+/*
+ *  call-seq:
+ *    initialize(conn, dir_alias = nil, filename = nil)
+ *
+ *  Creates a BFILE object.
+ *  This is correspond to {http://docs.oracle.com/cd/E11882_01/server.112/e17118/functions019.htm#sthref953 BFILENAME}.
+ *
+ *  @param [OCI8] conn
+ *  @param [String] dir_alias  a directory object created by
+ *    {http://docs.oracle.com/cd/E11882_01/server.112/e17118/statements_5007.htm "CREATE DIRECTORY"}.
+ *  @param [String] filename
+ *  @return [OCI8::BFILE]
+ */
 static VALUE oci8_bfile_initialize(int argc, VALUE *argv, VALUE self)
 {
     oci8_lob_t *lob = DATA_PTR(self);
@@ -574,6 +779,11 @@
     return Qnil;
 }
 
+/*
+ *  Returns the directory object name.
+ *
+ *  @return [String]
+ */
 static VALUE oci8_bfile_get_dir_alias(VALUE self)
 {
     VALUE dir_alias;
@@ -582,6 +792,11 @@
     return dir_alias;
 }
 
+/*
+ *  Returns the file name.
+ *
+ *  @return [String]
+ */
 static VALUE oci8_bfile_get_filename(VALUE self)
 {
     VALUE filename;
@@ -590,6 +805,14 @@
     return filename;
 }
 
+/*
+ *  call-seq:
+ *    dir_alias = name
+ *
+ *  Changes the directory object name.
+ *
+ *  @param [String] name
+ */
 static VALUE oci8_bfile_set_dir_alias(VALUE self, VALUE dir_alias)
 {
     VALUE filename;
@@ -601,6 +824,14 @@
     return dir_alias;
 }
 
+/*
+ *  call-seq:
+ *    filename = name
+ *
+ *  Changes the file name.
+ *
+ *  @param [String] name
+ */
 static VALUE oci8_bfile_set_filename(VALUE self, VALUE filename)
 {
     VALUE dir_alias;
@@ -612,6 +843,11 @@
     return filename;
 }
 
+/*
+ *  Returns <code>true</code> when the BFILE exists on the server's operating system.
+ *
+ *  @return [true or false]
+ */
 static VALUE oci8_bfile_exists_p(VALUE self)
 {
     oci8_lob_t *lob = DATA_PTR(self);
@@ -623,6 +859,39 @@
     return flag ? Qtrue : Qfalse;
 }
 
+/*
+ *  Document-method: OCI8::BFILE#truncate
+ *
+ *  call-seq:
+ *    truncate(length)
+ *
+ *  Raises <code>RuntimeError</code>.
+ *
+ *  @raise [RuntimeError] cannot modify a read-only BFILE object
+ */
+
+/*
+ *  Document-method: OCI8::BFILE#size=
+ *
+ *  call-seq:
+ *    size = length
+ *
+ *  Raises <code>RuntimeError</code>.
+ *
+ *  @raise [RuntimeError] cannot modify a read-only BFILE object
+ */
+
+/*
+ *  Document-method: OCI8::BFILE#write
+ *
+ *  call-seq:
+ *    write(data)
+ *
+ *  Raises <code>RuntimeError</code>.
+ *
+ *  @raise [RuntimeError] cannot modify a read-only BFILE object
+ */
+
 static VALUE oci8_bfile_error(VALUE self, VALUE dummy)
 {
     rb_raise(rb_eRuntimeError, "cannot modify a read-only BFILE object");
@@ -761,6 +1030,12 @@
     seek_cur = rb_eval_string("::IO::SEEK_CUR");
     seek_end = rb_eval_string("::IO::SEEK_END");
 
+#if 0
+    cOCIHandle = rb_define_class("OCIHandle", rb_cObject);
+    cOCI8 = rb_define_class("OCI8", cOCIHandle);
+    cOCI8LOB = rb_define_class_under(cOCI8, "LOB", cOCIHandle);
+#endif
+
     cOCI8LOB = oci8_define_class_under(cOCI8, "LOB", &oci8_lob_vtable);
     cOCI8CLOB = rb_define_class_under(cOCI8, "CLOB", cOCI8LOB);
     cOCI8NCLOB = rb_define_class_under(cOCI8, "NCLOB", cOCI8LOB);

Modified: trunk/ruby-oci8/ext/oci8/win32.c
===================================================================
--- trunk/ruby-oci8/ext/oci8/win32.c	2012-04-06 12:26:57 UTC (rev 501)
+++ trunk/ruby-oci8/ext/oci8/win32.c	2012-04-08 11:32:55 UTC (rev 502)
@@ -13,6 +13,14 @@
 #endif
 #include <windows.h>
 
+/*
+ *  Document-module: OCI8::Win32Util
+ *
+ *  Windows specific utility module.
+ *
+ *  @private
+ */
+
 NORETURN(static void raise_error(void));
 
 static void raise_error(void)
@@ -33,6 +41,11 @@
     rb_raise(rb_eRuntimeError, "%s", msg);
 }
 
+/*
+ *  Returns the full path of OCI.DLL used by the current process.
+ *
+ *  @return [String]
+ */
 static VALUE dll_path(VALUE module)
 {
     HMODULE hModule;
@@ -120,6 +133,15 @@
     return Qnil;
 }
 
+/*
+ *  Enumerates full clients' Oracle homes and NLS_LANG parameters
+ *  registerd in the Windows registry.
+ *
+ *  @yield [oracle_home, nls_lang]
+ *  @yieldparam [String] oracle_home
+ *  @yieldparam [String] nls_lang
+ *  @return [nil]
+ */
 static VALUE enum_homes(VALUE module)
 {
     enum_homes_arg_t arg;

Modified: trunk/ruby-oci8/lib/oci8/oracle_version.rb
===================================================================
--- trunk/ruby-oci8/lib/oci8/oracle_version.rb	2012-04-06 12:26:57 UTC (rev 501)
+++ trunk/ruby-oci8/lib/oci8/oracle_version.rb	2012-04-08 11:32:55 UTC (rev 502)
@@ -2,14 +2,16 @@
 #
 # Copyright (C) 2009 KUBO Takehiro <kubo at jiubao.org>
 
-#--
-
+#
 class OCI8
 
-  # A data class, representing Oracle version.
+  # The data class, representing Oracle version.
   #
   # Oracle version is represented by five numbers:
   # *major*, *minor*, *update*, *patch* and *port_update*.
+  #
+  # @see OCI8.oracle_client_version
+  # @see OCI8#oracle_server_version
   class OracleVersion
     include Comparable
 
@@ -24,7 +26,7 @@
     # The fourth part of the Oracle version.
     attr_reader :port_update
 
-    # Creates a OCI8::OracleVersion object.
+    # Creates an OCI8::OracleVersion object.
     #
     # If the first argument _arg_ is a String, it is parsed as dotted
     # version string. If it is bigger than 0x08000000, it is parsed as
@@ -33,20 +35,32 @@
     # patch and port_update. Unspecified version numbers are zeros by
     # default.
     #
-    # == Example
-    #   oraver = OCI8::OracleVersion.new('10.2.0.4')
-    #   oraver.major       # => 10
+    # @example
+    #   # When the first argument is a String,
+    #   oraver = OCI8::OracleVersion.new('11.2.0.3')
+    #   oraver.major       # => 11
     #   oraver.minor       # =>  2
     #   oraver.update      # =>  0
-    #   oraver.patch       # =>  4
+    #   oraver.patch       # =>  3
     #   oraver.port_update # =>  0
     #
-    #   oraver = OCI8::OracleVersion.new(0x0a200400)
-    #   oraver.major       # => 10
+    #   # When the first argument is bigger than 0x08000000,
+    #   oraver = OCI8::OracleVersion.new(0x0b200300)
+    #   oraver.major       # => 11
     #   oraver.minor       # =>  2
     #   oraver.update      # =>  0
-    #   oraver.patch       # =>  4
+    #   oraver.patch       # =>  3
     #   oraver.port_update # =>  0
+    #
+    #   # Otherwise,
+    #   oraver = OCI8::OracleVersion.new(11, 2, 0, 3)
+    #   oraver.major       # => 11
+    #   oraver.minor       # =>  2
+    #   oraver.update      # =>  0
+    #   oraver.patch       # =>  3
+    #   oraver.port_update # =>  0
+    #
+    # @return [OCI8::OracleVersion]
     def initialize(arg, minor = nil, update = nil, patch = nil, port_update = nil)
       if arg.is_a? String
         major, minor, update, patch, port_update = arg.split('.').collect do |v|
@@ -68,13 +82,12 @@
       @port_update = port_update || 0
     end
 
-    # :call-seq:
-    #   oraver <=> other_oraver -> -1, 0, +1
+    # Compares +self+ and +other+.
     #
-    # Compares +oraver+ and +other_oraver+.
+    # <=> is the basis for the methods <, <=, ==, >, >=, and between?,
+    # included from the Comparable module.
     #
-    # <=> is the basis for the methods <, <=, ==, >, >=, and between?,
-    # included from module Comparable.
+    # @return [-1, 0, +1]
     def <=>(other)
       cmp = @major <=> other.major
       return cmp if cmp != 0
@@ -87,57 +100,50 @@
       @port_update <=> other.port_update
     end
 
-    # :call-seq:
-    #   oraver.to_i -> integer
-    #
     # Returns an integer number contains 5-digit Oracle version.
     #
     # If the hexadecimal notation is 0xAABCCDEE, *major*, *minor*,
     # *update*, *patch* and *port_update* are 0xAA, 0xB, 0xCC, 0xD and
     # 0xEE respectively.
     #
-    # == Example
-    #   oraver = OCI8::OracleVersion.new('10.2.0.4')
-    #   oraver.to_i          # => 169870336
-    #   '%08x' % oraver.to_i # => "0a200400"
+    # @example
+    #   oraver = OCI8::OracleVersion.new('11.2.0.3')
+    #   oraver.to_i          # => 186647296
+    #   '%08x' % oraver.to_i # => "0b200300"
+    #
+    # @return [Integer]
     def to_i
       (@major << 24) | (@minor << 20) | (@update << 12) | (@patch << 8) | @port_update
     end
 
-    # :call-seq:
-    #   oraver.to_s -> string
-    #
     # Returns a dotted version string of the Oracle version.
     #
-    # == Example
-    #   oraver = OCI8::OracleVersion.new('10.2.0.4')
-    #   oraver.to_s          # => '10.2.0.4.0'
+    # @example
+    #   oraver = OCI8::OracleVersion.new('11.2.0.3')
+    #   oraver.to_s          # => '11.2.0.3.0'
+    #
+    # @return [Integer]
     def to_s
       format('%d.%d.%d.%d.%d', @major, @minor, @update, @patch, @port_update)
     end
 
-    # :call-seq:
-    #   oraver.eql? other -> true or false
+    # Returns true if +self+ and +other+ are the same type and have
+    # equal values.
     #
-    # Returns true if +oraver+ and +other+ are the same type and have
-    # equal values.
-    #--
-    # This is for class Hash to test members for equality.
+    # @return [true or false]
     def eql?(other)
       other.is_a? OCI8::OracleVersion and (self <=> other) == 0
     end
 
-    # :call-seq:
-    #   oraver.hash -> integer
+    # Returns a hash based on the value of +self+.
     #
-    # Returns a hash based on the value of +oraver+.
-    #--
-    # This is for class Hash.
+    # @return [Integer]
     def hash
       to_i
     end
 
-    def inspect # :nodoc:
+    # @private
+    def inspect
       "#<#{self.class.to_s}: #{self.to_s}>"
     end
   end



More information about the ruby-oci8-commit mailing list