[ruby-oci8-commit] [540] trunk/ruby-oci8: Change comments for yard command.

nobody at rubyforge.org nobody at rubyforge.org
Sun Nov 11 11:56:29 UTC 2012


Revision: 540
Author:   kubo
Date:     2012-11-11 11:56:27 +0000 (Sun, 11 Nov 2012)
Log Message:
-----------
Change comments for yard command.

Modified Paths:
--------------
    trunk/ruby-oci8/ChangeLog
    trunk/ruby-oci8/Makefile
    trunk/ruby-oci8/ext/oci8/encoding.c
    trunk/ruby-oci8/ext/oci8/oci8.c
    trunk/ruby-oci8/ext/oci8/oci8.h
    trunk/ruby-oci8/ext/oci8/oci8lib.c
    trunk/ruby-oci8/ext/oci8/ocinumber.c
    trunk/ruby-oci8/lib/oci8/connection_pool.rb
    trunk/ruby-oci8/lib/oci8/datetime.rb
    trunk/ruby-oci8/lib/oci8/encoding-init.rb
    trunk/ruby-oci8/lib/oci8/metadata.rb
    trunk/ruby-oci8/lib/oci8/object.rb
    trunk/ruby-oci8/lib/oci8/oci8.rb
    trunk/ruby-oci8/lib/oci8.rb.in

Modified: trunk/ruby-oci8/ChangeLog
===================================================================
--- trunk/ruby-oci8/ChangeLog	2012-11-11 10:03:11 UTC (rev 539)
+++ trunk/ruby-oci8/ChangeLog	2012-11-11 11:56:27 UTC (rev 540)
@@ -1,4 +1,13 @@
 2012-11-11  KUBO Takehiro  <kubo at jiubao.org>
+	* Makefile: add doc and copy-doc targets to generate document by yard command.
+	* ext/oci8/oci8.c, ext/oci8/oci8.h, ext/oci8/oci8lib.c: change
+	    protoptype definition of Init_oci8 for yard command to parse it.
+	* ext/oci8/encoding.c, ext/oci8/oci8.c, ext/oci8/ocinumber.c,
+	  lib/oci8.rb.in, lib/oci8/connection_pool.rb, lib/oci8/datetime.rb,
+	  lib/oci8/encoding-init.rb, lib/oci8/metadata.rb, lib/oci8/object.rb,
+	  lib/oci8/oci8.rb: change comments for yard command.
+
+2012-11-11  KUBO Takehiro  <kubo at jiubao.org>
 	* ext/oci8/oci8.h: update RB_GC_GUARD as ruby 1.9.2 defines.
 	* test/test_break.rb: fix tests for rubinius 1.2.4 and 2.0.0.
 

Modified: trunk/ruby-oci8/Makefile
===================================================================
--- trunk/ruby-oci8/Makefile	2012-11-11 10:03:11 UTC (rev 539)
+++ trunk/ruby-oci8/Makefile	2012-11-11 11:56:27 UTC (rev 540)
@@ -1,6 +1,5 @@
 VERSION = `cat VERSION`
 RUBY = ruby -w
-RDOC = rdoc
 
 all: build
 
@@ -29,11 +28,16 @@
 	astyle --options=none --style=linux --indent=spaces=4 --brackets=linux --suffix=none ext/oci8/*.[ch]
 
 # internal use only
-.PHONY: rdoc run-rdoc
+.PHONY: dist dist-check doc copy-doc
 
-rdoc:
-	TZ= $(RDOC) -o rdoc -c us-ascii --threads=1 -W http://ruby-oci8.rubyforge.org/svn/trunk/ruby-oci8/ ext/oci8 lib
+doc:
+	rm -rf doc
+	TZ= yard
+	echo DirectoryIndex frames.html > doc/.htaccess
 
+copy-doc: doc
+	rsync -avz doc/ rubyforge.org:/var/www/gforge-projects/ruby-oci8/en
+
 dist:
 	-rm -rf ruby-oci8-$(VERSION)
 	mkdir ruby-oci8-$(VERSION)

Modified: trunk/ruby-oci8/ext/oci8/encoding.c
===================================================================
--- trunk/ruby-oci8/ext/oci8/encoding.c	2012-11-11 10:03:11 UTC (rev 539)
+++ trunk/ruby-oci8/ext/oci8/encoding.c	2012-11-11 11:56:27 UTC (rev 540)
@@ -30,8 +30,6 @@
  * call-seq:
  *   charset_id2name(charset_id) -> charset_name
  *
- * <b>(new in 2.0.0)</b>
- *
  * Returns the Oracle character set name from the specified
  * character set ID if it is valid. Otherwise, +nil+ is returned.
  *
@@ -48,6 +46,9 @@
  *     :name := nls_charset_name(:csid);
  *   END;
  *
+ * @param [Fixnum] charset_id   Oracle character set id
+ * @return [String]             Oracle character set name or nil
+ * @since 2.0.0
  */
 VALUE oci8_charset_id2name(VALUE svc, VALUE csid)
 {
@@ -104,8 +105,6 @@
  * call-seq:
  *   charset_name2id(charset_name) -> charset_id
  *
- * <b>(new in 2.0.0)</b>
- *
  * Returns the Oracle character set ID for the specified Oracle
  * character set name if it is valid. Othewise, +nil+ is returned.
  *
@@ -122,6 +121,9 @@
  *     :csid := nls_charset_id(:name);
  *   END;
  *
+ * @param [String] charset_name   Oracle character set name
+ * @return [Fixnum]               Oracle character set id or nil
+ * @since 2.0.0
  */
 static VALUE oci8_charset_name2id(VALUE svc, VALUE name)
 {
@@ -176,12 +178,13 @@
  * call-seq:
  *   OCI8.nls_ratio -> integer
  *
- * <b>(new in 2.1.0)</b>
- *
  * Gets NLS ratio, maximum number of bytes per one character of the
  * current NLS chracter set. It is a factor to calculate the
  * internal buffer size of a string bind variable whose nls length
  * semantics is char.
+ *
+ * @return [Fixnum]  NLS ratio
+ * @since 2.1.0
  */
 static VALUE oci8_get_nls_ratio(VALUE klass)
 {
@@ -192,11 +195,12 @@
  * call-seq:
  *   OCI8.nls_ratio = integer
  *
- * <b>(new in 2.1.0)</b>
- *
  * Sets NLS ratio, maximum number of bytes per one character of the
  * current NLS chracter set. It is initialized in 'oci8/encoding-init.rb'
  * when oci8 is required. You have no need to set it explicitly.
+ *
+ * @param [Fixnum] integer  NLS ratio
+ * @since 2.1.0
  */
 static VALUE oci8_set_nls_ratio(VALUE klass, VALUE val)
 {
@@ -214,8 +218,6 @@
  * call-seq:
  *    OCI8.encoding -> enc
  *
- * <b>(new in 2.0.0 and ruby 1.9)</b>
- *
  * Returns the Oracle client encoding.
  *
  * When string data, such as SQL statements and bind variables,
@@ -238,6 +240,9 @@
  *
  * If +OCI8.encoding+ is ASCII-8BIT, no encoding conversions
  * are done.
+ *
+ * @return [Encoding]
+ * @since 2.0.0 and ruby 1.9
  */
 static VALUE oci8_get_encoding(VALUE klass)
 {
@@ -248,11 +253,12 @@
  * call-seq:
  *   OCI8.encoding = enc or nil
  *
- * <b>(new in 2.0.0 and ruby 1.9)</b>
- *
  * Sets Oracle client encoding. You must not use this method.
  * You should set the environment variable NLS_LANG properly to
  * change +OCI8.encoding+.
+ *
+ * @param [Encoding]  enc
+ * @since 2.0.0 and ruby 1.9
  */
 static VALUE oci8_set_encoding(VALUE klass, VALUE encoding)
 {

Modified: trunk/ruby-oci8/ext/oci8/oci8.c
===================================================================
--- trunk/ruby-oci8/ext/oci8/oci8.c	2012-11-11 10:03:11 UTC (rev 539)
+++ trunk/ruby-oci8/ext/oci8/oci8.c	2012-11-11 11:56:27 UTC (rev 540)
@@ -208,6 +208,8 @@
  *   # When NLS_LANG is FRENCH_FRANCE.AL32UTF8
  *   OCI8.error_message(1) # => "ORA-00001: violation de contrainte unique (%s.%s)"
  *
+ * @param [Fixnum] message_no   Oracle error message number
+ * @return [String]             Oracle error message
  */
 static VALUE oci8_s_error_message(VALUE klass, VALUE msgid)
 {
@@ -763,11 +765,11 @@
  * call-seq:
  *   oracle_server_vernum -> an integer
  *
- * <b>(new in 2.0.1)</b>
- *
  * Returns a numerical format of the Oracle server version.
  *
  * See also: #oracle_server_version
+ *
+ * @since 2.0.1
  */
 static VALUE oci8_oracle_server_vernum(VALUE self)
 {
@@ -783,8 +785,6 @@
  * call-seq:
  *   ping -> true or false
  *
- * <b>(new in 2.0.2)</b>
- *
  * Makes a round trip call to the server to confirm that the connection and
  * the server are active.
  *
@@ -797,6 +797,8 @@
  *
  * === Oracle 10.1 client or lower
  * A simple PL/SQL block "BEGIN NULL; END;" is executed to make a round trip call.
+ *
+ * @since 2.0.2
  */
 static VALUE oci8_ping(VALUE self)
 {
@@ -817,8 +819,6 @@
  * call-seq:
  *   client_identifier = string or nil
  *
- * <b>(new in 2.0.3)</b>
- *
  * Sets the client ID. This information is stored in the V$SESSION
  * view.
  *
@@ -839,6 +839,7 @@
  *
  * See {Oracle Manual: Oracle Database PL/SQL Packages and Types Reference}[http://download.oracle.com/docs/cd/B19306_01/appdev.102/b14258/d_sessio.htm#i996935]
  *
+ * @since 2.0.3
  */
 static VALUE oci8_set_client_identifier(VALUE self, VALUE val)
 {
@@ -884,8 +885,6 @@
  * call-seq:
  *   module = string or nil
  *
- * <b>(new in 2.0.3)</b>
- *
  * Sets the name of the current module. This information is
  * stored in the V$SESSION view and is also stored in the V$SQL view
  * and the V$SQLAREA view when a SQL statement is executed and the SQL
@@ -913,6 +912,7 @@
  *
  * See {Oracle Manual: Oracle Database PL/SQL Packages and Types Reference}[http://download.oracle.com/docs/cd/B19306_01/appdev.102/b14258/d_appinf.htm#i999254]
  *
+ * @since 2.0.3
  */
 static VALUE oci8_set_module(VALUE self, VALUE val)
 {
@@ -958,8 +958,6 @@
  * call-seq:
  *   action = string or nil
  *
- * <b>(new in 2.0.3)</b>
- *
  * Sets the name of the current action within the current module.
  * This information is stored in the V$SESSION view and is also
  * stored in the V$SQL view and the V$SQLAREA view when a SQL
@@ -983,6 +981,7 @@
  *
  * See {Oracle Manual: Oracle Database PL/SQL Packages and Types Reference}[http://download.oracle.com/docs/cd/B19306_01/appdev.102/b14258/d_appinf.htm#i999254]
  *
+ * @since 2.0.3
  */
 static VALUE oci8_set_action(VALUE self, VALUE val)
 {
@@ -1025,8 +1024,6 @@
  * call-seq:
  *   client_info = string or nil
  *
- * <b>(new in 2.0.3)</b>
- *
  * Sets additional information about the client application.
  * This information is stored in the V$SESSION view.
  *
@@ -1046,6 +1043,8 @@
  *   END;
  *
  * See {Oracle Manual: Oracle Database PL/SQL Packages and Types Reference}[http://download.oracle.com/docs/cd/B19306_01/appdev.102/b14258/d_appinf.htm#CHEJCFGG]
+ *
+ * @since 2.0.3
  */
 static VALUE oci8_set_client_info(VALUE self, VALUE val)
 {
@@ -1084,11 +1083,11 @@
     return val;
 }
 
-VALUE Init_oci8(void)
+void Init_oci8(VALUE *out)
 {
     VALUE obj;
     oci8_base_t *base;
-#if 0
+#if /* for yard */ 0
     oci8_cOCIHandle = rb_define_class("OCIHandle", rb_cObject);
     cOCI8 = rb_define_class("OCI8", oci8_cOCIHandle);
 #endif
@@ -1147,7 +1146,7 @@
     rb_define_method(cOCI8, "action=", oci8_set_action, 1);
     rb_define_method(cOCI8, "client_info=", oci8_set_client_info, 1);
     rb_define_attr(cOCI8, "last_error", 1, 1);
-    return cOCI8;
+    *out = cOCI8;
 }
 
 oci8_svcctx_t *oci8_get_svcctx(VALUE obj)

Modified: trunk/ruby-oci8/ext/oci8/oci8.h
===================================================================
--- trunk/ruby-oci8/ext/oci8/oci8.h	2012-11-11 10:03:11 UTC (rev 539)
+++ trunk/ruby-oci8/ext/oci8/oci8.h	2012-11-11 11:56:27 UTC (rev 540)
@@ -490,7 +490,7 @@
 void Init_oci8_handle(void);
 
 /* oci8.c */
-VALUE Init_oci8(void);
+void Init_oci8(VALUE *out);
 void oci8_do_parse_connect_string(VALUE conn_str, VALUE *user, VALUE *pass, VALUE *dbname, VALUE *mode);
 oci8_svcctx_t *oci8_get_svcctx(VALUE obj);
 OCISvcCtx *oci8_get_oci_svcctx(VALUE obj);

Modified: trunk/ruby-oci8/ext/oci8/oci8lib.c
===================================================================
--- trunk/ruby-oci8/ext/oci8/oci8lib.c	2012-11-11 10:03:11 UTC (rev 539)
+++ trunk/ruby-oci8/ext/oci8/oci8lib.c	2012-11-11 11:56:27 UTC (rev 540)
@@ -101,7 +101,7 @@
     Init_oci8_handle();
 
     /* OCI8 class */
-    cOCI8 = Init_oci8();
+    Init_oci8(&cOCI8);
 
     /* OCI8::ConnectionPool class */
     Init_oci8_connection_pool(cOCI8);

Modified: trunk/ruby-oci8/ext/oci8/ocinumber.c
===================================================================
--- trunk/ruby-oci8/ext/oci8/ocinumber.c	2012-11-11 10:03:11 UTC (rev 539)
+++ trunk/ruby-oci8/ext/oci8/ocinumber.c	2012-11-11 11:56:27 UTC (rev 540)
@@ -1262,7 +1262,7 @@
  *
  *  @param [Integer]
  *  @return [OraNumber]
- *  @todo returns {Integer} when <i>decplace</i> is not specified.
+ *  @todo returns <i>Integer</i> when <i>decplace</i> is not specified.
  */
 static VALUE onum_trunc(int argc, VALUE *argv, VALUE self)
 {

Modified: trunk/ruby-oci8/lib/oci8/connection_pool.rb
===================================================================
--- trunk/ruby-oci8/lib/oci8/connection_pool.rb	2012-11-11 10:03:11 UTC (rev 539)
+++ trunk/ruby-oci8/lib/oci8/connection_pool.rb	2012-11-11 11:56:27 UTC (rev 540)
@@ -27,9 +27,6 @@
   #
   class ConnectionPool
 
-    # call-seq:
-    #   timeout -> integer
-    #
     # Connections idle for more than this time value (in seconds) are
     # terminated, to maintain an optimum number of open
     # connections. If it is zero, the connections are never timed out.
@@ -38,21 +35,19 @@
     # <b>Note:</b> Shrinkage of the pool only occurs when there is a network
     # round trip. If there are no operations, then the connections
     # stay alive.
+    #
+    # @return [Integer]
     def timeout
       attr_get_ub4(OCI_ATTR_CONN_TIMEOUT)
     end
 
-    # call-seq:
-    #   timeout = integer
-    #
     # Changes the timeout in seconds to terminate idle connections.
+    #
+    # @param [Integer] val
     def timeout=(val)
       attr_set_ub4(OCI_ATTR_CONN_TIMEOUT, val)
     end
 
-    # call-seq:
-    #   nowait? -> true or false
-    #
     # If true, an error is thrown when all the connections in the pool
     # are busy and the number of connections has already reached the
     # maximum. Otherwise the call waits till it gets a connection.
@@ -61,52 +56,46 @@
       attr_get_ub1(OCI_ATTR_CONN_NOWAIT) != 0
     end
 
-    # call-seq:
-    #   nowait = true or false
-    #
     # Changes the behavior when all the connections in the pool
     # are busy and the number of connections has already reached the
     # maximum.
+    #
+    # @param [Boolean] val
     def nowait=(val)
       attr_set_ub1(OCI_ATTR_CONN_NOWAIT, val ? 1 : 0)
     end
 
-    # call-seq:
-    #   busy_count -> integer
-    #
     # Returns the number of busy physical connections.
+    #
+    # @return [Integer]
     def busy_count
       attr_get_ub4(OCI_ATTR_CONN_BUSY_COUNT)
     end
 
-    # call-seq:
-    #   open_count -> integer
-    #
     # Returns the number of open physical connections.
+    #
+    # @return [Integer]
     def open_count
       attr_get_ub4(OCI_ATTR_CONN_OPEN_COUNT)
     end
 
-    # call-seq:
-    #   min -> integer
-    #
     # Returns the number of minimum physical connections.
+    #
+    # @return [Integer]
     def min
       attr_get_ub4(OCI_ATTR_CONN_MIN)
     end
 
-    # call-seq:
-    #   max -> integer
-    #
     # Returns the number of maximum physical connections.
+    #
+    # @return [Integer]
     def max
       attr_get_ub4(OCI_ATTR_CONN_MAX)
     end
 
-    # call-seq:
-    #   incr -> integer
-    #
     # Returns the connection increment parameter.
+    #
+    # @return [Integer]
     def incr
       attr_get_ub4(OCI_ATTR_CONN_INCR)
     end

Modified: trunk/ruby-oci8/lib/oci8/datetime.rb
===================================================================
--- trunk/ruby-oci8/lib/oci8/datetime.rb	2012-11-11 10:03:11 UTC (rev 539)
+++ trunk/ruby-oci8/lib/oci8/datetime.rb	2012-11-11 11:56:27 UTC (rev 540)
@@ -4,24 +4,22 @@
 
   module BindType
 
-    # call-seq:
-    #   OCI8::BindType.default_timezone -> :local or :utc
-    #
     # Returns the default time zone when using Oracle 8.x client.
     # The value is unused when using Oracle 9i or upper client.
     #
     # See also: OCI8::BindType::Time
+    #
+    # @return [:local or :utc]
     def self.default_timezone
       OCI8::BindType::Util.default_timezone
     end
 
-    # call-seq:
-    #   OCI8::BindType.default_timezone = :local or :utc
-    #
     # Sets the default time zone when using Oracle 8.x client.
     # The value is unused when using Oracle 9i or upper client.
     #
     # See also: OCI8::BindType::Time
+    #
+    # @param [:local or :utc]  tz
     def self.default_timezone=(tz)
       OCI8::BindType::Util.default_timezone = tz
     end
@@ -538,22 +536,18 @@
       @@fsec = @@sec / 1000000000
       @@unit = :second
 
-      # call-seq:
-      #   OCI8::BindType::IntervalDS.unit -> :second or :day
-      #
-      # (new in 2.0.3)
-      #
       # Retrieves the unit of interval.
+      #
+      # @return [:second or :day]
+      # @since 2.0.3
       def self.unit
         @@unit
       end
 
-      # call-seq:
-      #   OCI8::BindType::IntervalDS.unit = :second or :day
-      #
-      # (new in 2.0.3)
-      #
       # Changes the unit of interval. :second is the default.
+      #
+      # @param [:second or :day] val
+      # @since 2.0.3
       def self.unit=(val)
         case val
         when :second, :day

Modified: trunk/ruby-oci8/lib/oci8/encoding-init.rb
===================================================================
--- trunk/ruby-oci8/lib/oci8/encoding-init.rb	2012-11-11 10:03:11 UTC (rev 539)
+++ trunk/ruby-oci8/lib/oci8/encoding-init.rb	2012-11-11 11:56:27 UTC (rev 540)
@@ -35,6 +35,7 @@
     end
   else
     warn "Warning: NLS_LANG is not set. fallback to US7ASCII."
+    # @private
     @@client_charset_name = 'US7ASCII'
   end
 

Modified: trunk/ruby-oci8/lib/oci8/metadata.rb
===================================================================
--- trunk/ruby-oci8/lib/oci8/metadata.rb	2012-11-11 10:03:11 UTC (rev 539)
+++ trunk/ruby-oci8/lib/oci8/metadata.rb	2012-11-11 11:56:27 UTC (rev 540)
@@ -59,30 +59,27 @@
       end
       private :num_params
 
-      # call-seq:
-      #   obj_id -> integer or nil
-      #
       # Returns the object ID, which is the same as the value of the
       # OBJECT_ID column from ALL_OBJECTS. It returns +nil+
       # if the database object doesn't have ID.
+      #
+      # @return [Integer or nil]
       def obj_id
         attr_get_ub4(OCI_ATTR_OBJ_ID)
       end
 
-      # call-seq:
-      #   obj_name -> string
-      #
       # Retruns the object name such as table name, view name,
       # procedure name, and so on.
+      #
+      # @return [String]
       def obj_name
         attr_get_string(OCI_ATTR_OBJ_NAME)
       end
 
-      # call-seq:
-      #   obj_schema -> string
-      #
       # Retruns the schema name. It returns +nil+
       # if the database object is not defined just under a schema.
+      #
+      # @return [String]
       def obj_schema
         attr_get_string(OCI_ATTR_OBJ_SCHEMA)
       end
@@ -370,10 +367,9 @@
 
       ## Table 6-2 Attributes Belonging to Tables or Views
 
-      # call-seq:
-      #   num_cols -> integer
-      #
       # Returns number of columns
+      #
+      # @return [Integer]
       def num_cols
         attr_get_ub2(OCI_ATTR_NUM_COLS)
       end
@@ -384,19 +380,15 @@
       end
       private :list_columns
 
-      # call-seq:
-      #   type_metadata -> an OCI8::Metadata::Type or nil
-      #
       # Retruns an instance of OCI8::Metadata::Type if the table is an
       # {object table}[http://download.oracle.com/docs/cd/B28359_01/appdev.111/b28371/adobjint.htm#sthref61].
       # Otherwise, +nil+.
+      #
+      # @return [OCI8::Metadata::Type or nil]
       def type_metadata
         __type_metadata(OCI8::Metadata::Type) if is_typed?
       end
 
-      # call-seq:
-      #   is_temporary? -> true or false
-      #
       # Returns +true+ if the table is a
       # {temporary table}[http://download.oracle.com/docs/cd/B28359_01/server.111/b28318/schema.htm#i16096].
       # Otherwise, +false+.
@@ -404,51 +396,42 @@
         attr_get_ub1(OCI_ATTR_IS_TEMPORARY) != 0
       end
 
-      # call-seq:
-      #   is_typed? -> true or false
-      #
       # Returns +true+ if the table is a object table. Otherwise, +false+.
       def is_typed?
         attr_get_ub1(OCI_ATTR_IS_TYPED) != 0
       end
 
-      # call-seq:
-      #   duration -> :transaction, :session or nil
-      #
       # Retruns +:transaction+ if the table is a
       # {transaction-specific temporary table}[http://download.oracle.com/docs/cd/B28359_01/server.111/b28286/statements_7002.htm#i2189569].
       # +:session+ if it is a
       # {session-specific temporary table}[http://download.oracle.com/docs/cd/B28359_01/server.111/b28286/statements_7002.htm#i2189569].
       # Otherwise, +nil+.
+      #
+      # @return [:transaction, :session or nil]
       def duration
         __duration
       end
 
       ## Table 6-3 Attributes Specific to Tables
 
-      # call-seq:
-      #   dba -> integer
-      #
       # Returns a Data Block Address(DBA) of the segment header.
       #
       # The dba is converted to the file number and the block number
       # by DBMS_UTILITY.DATA_BLOCK_ADDRESS_FILE and
       # DBMS_UTILITY.DATA_BLOCK_ADDRESS_BLOCK respectively.
+      #
+      # @return [Integer]
       def dba
         attr_get_ub4(OCI_ATTR_RDBA)
       end
 
-      # call-seq:
-      #   tablespace -> integer
-      #
       # Returns a tablespace number the table resides in.
+      #
+      # @return [Integer]
       def tablespace
         __word(OCI_ATTR_TABLESPACE)
       end
 
-      # call-seq:
-      #   clustered? -> true or false
-      #
       # Returns +true+ if the table is part of a 
       # cluster[http://download.oracle.com/docs/cd/B28359_01/server.111/b28318/schema.htm#CNCPT608].
       # Otherwise, +false+.
@@ -456,9 +439,6 @@
         attr_get_ub1(OCI_ATTR_CLUSTERED) != 0
       end
 
-      # call-seq:
-      #   partitioned? -> true or false
-      #
       # Returns +true+ if the table is a
       # {partitioned table}[http://download.oracle.com/docs/cd/B28359_01/server.111/b28318/partconc.htm#i449863].
       # Otherwise, +false+.
@@ -466,9 +446,6 @@
         attr_get_ub1(OCI_ATTR_PARTITIONED) != 0
       end
 
-      # call-seq:
-      #   index_only? -> true or false
-      #
       # Returns +true+ if the table is an
       # {index-organized table}[http://download.oracle.com/docs/cd/B28359_01/server.111/b28318/schema.htm#i23877]
       # Otherwise, +false+.
@@ -476,10 +453,9 @@
         attr_get_ub1(OCI_ATTR_INDEX_ONLY) != 0
       end
 
-      # call-seq:
-      #   columns -> list of column information
+      # Returns column information of the table.
       #
-      # Returns an array of OCI8::Metadata::Column of the table.
+      # @return [array of OCI8::Metadata::Column]
       def columns
         @columns ||= list_columns.to_a
       end
@@ -502,10 +478,9 @@
 
       ## Table 6-2 Attributes Belonging to Tables or Views
 
-      # call-seq:
-      #   num_cols -> integer
-      #
       # Returns number of columns
+      #
+      # @return [Integer]
       def num_cols
         attr_get_ub2(OCI_ATTR_NUM_COLS)
       end
@@ -536,10 +511,9 @@
       #  __duration
       #end
 
-      # call-seq:
-      #   columns -> list of column information
+      # Returns column information of the view.
       #
-      # Returns an array of OCI8::Metadata::Column of the table.
+      # @return [array of OCI8::Metadata::Column]
       def columns
         @columns ||= list_columns.to_a
       end
@@ -574,9 +548,6 @@
         super if is_standalone?
       end
 
-      # call-seq:
-      #   is_invoker_rights? -> true or false
-      #
       # Returns +true+ if the subprogram has
       # {invoker's rights}[http://download.oracle.com/docs/cd/B28359_01/appdev.111/b28370/subprograms.htm#i18574].
       # Otherwise, +false+.
@@ -593,29 +564,24 @@
       #end
       alias name obj_name # :nodoc: for backward compatibility
 
-      # call-seq:
-      #   overload_id -> integer or nil
-      #
       # Returns +nil+ for a standalone stored subprogram,
       # positive integer for a
       # {overloaded packaged subprogram}[http://download.oracle.com/docs/cd/B28359_01/appdev.111/b28370/subprograms.htm#i12352].
       # , otherwise zero.
+      #
+      # @return [Integer or nil]
       def overload_id
         attr_get_ub2(OCI_ATTR_OVERLOAD_ID) unless is_standalone?
       end
 
-      # call-seq:
-      #   arguments -> list of argument information
-      #
-      # Returns an array of OCI8::Metadata::Argument of the subprogram.
+      # Returns argument information of the subprogram.
       # If it is a function, the first array element is information of its return type.
+      #
+      # @return [array of OCI8::Metadata::Argument]
       def arguments
         @arguments ||= list_arguments.to_a
       end
 
-      # call-seq:
-      #   is_standalone? -> true or false
-      #
       # Returns +true+ if the subprogram is standalone, +false+
       # if packaged.
       def is_standalone?
@@ -674,9 +640,6 @@
       end
       private :list_subprograms
 
-      # call-seq:
-      #   is_invoker_rights? -> true or false
-      #
       # Returns +true+ if the package subprograms have
       # {invoker's rights}[http://download.oracle.com/docs/cd/B28359_01/appdev.111/b28370/subprograms.htm#i18574].
       # Otherwise, +false+.
@@ -684,10 +647,9 @@
         attr_get_ub1(OCI_ATTR_IS_INVOKER_RIGHTS) != 0
       end
 
-      # call-seq:
-      #   subprograms -> array
-      #
       # Returns an array of Function and Procedure defined within the Package.
+      #
+      # @return [array of OCI8::Metadata::Function and OCI8::Metadata::Procedure]
       def subprograms
         @subprograms ||= list_subprograms.to_a.each do |prog|
           prog.instance_variable_set(:@is_standalone, false)
@@ -712,27 +674,22 @@
         self
       end
 
-      # call-seq:
-      #   typecode -> :named_type or :named_collection
-      #
       # Returns +:named_type+ if the type is an object type,
       # +:named_collection+ if it is a nested table or a varray.
+      #
+      # @return [:named_type or :named_collection]
       def typecode
         __typecode(OCI_ATTR_TYPECODE)
       end
 
-      # call-seq:
-      #   collection_typecode -> :table, :varray or nil
-      #
       # Returns +:table+ if the type is a nested table,
       # +:varray+ if it is a varray. Otherwise, +nil+.
+      #
+      # @return [:table, :varray or nil]
       def collection_typecode
         __typecode(OCI_ATTR_COLLECTION_TYPECODE) if typecode == :named_collection
       end
 
-      # call-seq:
-      #   is_incomplete_type? -> boolean
-      #
       # Returns +true+ if the type is an
       # {incomplete type}[http://download.oracle.com/docs/cd/B28359_01/appdev.111/b28371/adobjmng.htm#i1003083],
       # which is used for {forward declaration}[http://en.wikipedia.org/wiki/Forward_declaration].
@@ -741,9 +698,6 @@
         attr_get_ub1(OCI_ATTR_IS_INCOMPLETE_TYPE) != 0
       end
 
-      # call-seq:
-      #   is_system_type? -> boolean
-      #
       # Always returns +false+ because there is no way to create
       # a type metadata object for a system type such as +NUMBER+,
       # +CHAR+ and +VARCHAR+.
@@ -751,9 +705,6 @@
         attr_get_ub1(OCI_ATTR_IS_SYSTEM_TYPE) != 0
       end
 
-      # call-seq:
-      #   is_predefined_type? -> boolean
-      #
       # Always returns +false+.
       #--
       # I don't know the definition of predefined type...
@@ -761,9 +712,6 @@
         attr_get_ub1(OCI_ATTR_IS_PREDEFINED_TYPE) != 0
       end
 
-      # call-seq:
-      #   is_transient_type? -> boolean
-      #
       # Always returns +false+ because there is no way to create
       # a type metadata object for a transient type, which is a type
       # dynamically created by C API.
@@ -771,9 +719,6 @@
         attr_get_ub1(OCI_ATTR_IS_TRANSIENT_TYPE) != 0
       end
 
-      # call-seq:
-      #   is_predefined_type? -> boolean
-      #
       # Always returns +false+.
       #--
       # I don't know the definition of system generated type.
@@ -782,9 +727,6 @@
         attr_get_ub1(OCI_ATTR_IS_SYSTEM_GENERATED_TYPE) != 0
       end
 
-      # call-seq:
-      #   has_nested_table? -> boolean
-      #
       # Returns +true+ if the type is a nested table or
       # has a nested table attribute.
       # Otherwise, +false+.
@@ -792,9 +734,6 @@
         attr_get_ub1(OCI_ATTR_HAS_NESTED_TABLE) != 0
       end
 
-      # call-seq:
-      #   has_lob? -> boolean
-      #
       # Returns +true+ if the type has a CLOB, NCLOB or BLOB
       # attribute.
       # Otherwise, +false+.
@@ -802,29 +741,24 @@
         attr_get_ub1(OCI_ATTR_HAS_LOB) != 0
       end
 
-      # call-seq:
-      #   has_file? -> boolean
-      #
       # Returns +true+ if the type has a BFILE attribute.
       # Otherwise, +false+.
       def has_file?
         attr_get_ub1(OCI_ATTR_HAS_FILE) != 0
       end
 
-      # call-seq:
-      #   collection_element -> element information of the collection type
-      #
-      # Returns an OCI8::Metadata::Collection if the type is a nested
+      # Returns element information of the collection type if the type is a nested
       # table or a varray.
       # Otherwise, +nil+.
+      #
+      # @return [OCI8::Metadata::Collection or nil]
       def collection_element
         __param(OCI_ATTR_COLLECTION_ELEMENT) if typecode == :named_collection
       end
 
-      # call-seq:
-      #   num_type_attrs -> integer
-      #
       # Returns number of type attributes.
+      #
+      # @return [Integer]
       def num_type_attrs
         attr_get_ub2(OCI_ATTR_NUM_TYPE_ATTRS)
       end
@@ -835,10 +769,9 @@
       end
       private :list_type_attrs
 
-      # call-seq:
-      #   num_type_methods -> integer
-      #
       # Returns number of type methods.
+      #
+      # @return [Integer]
       def num_type_methods
         attr_get_ub2(OCI_ATTR_NUM_TYPE_METHODS)
       end
@@ -849,29 +782,24 @@
       end
       private :list_type_methods
 
-      # call-seq:
-      #   map_method -> map method information
-      #
-      # Returns an instance of OCI8::Metadata::TypeMethod of a
+      # Returns information of the
       # {map method}[http://download.oracle.com/docs/cd/B28359_01/appdev.111/b28371/adobjbas.htm#sthref180]
       # if it is defined in the type. Otherwise, +nil+.
+      #
+      # @return [OCI8::Metadata::TypeMethod or nil]
       def map_method
         __param(OCI_ATTR_MAP_METHOD)
       end
 
-      # call-seq:
-      #   order_method -> order method information
-      #
-      # Returns an instance of OCI8::Metadata::TypeMethod of a
+      # Returns information of the
       # {order method}[http://download.oracle.com/docs/cd/B28359_01/appdev.111/b28371/adobjbas.htm#sthref185]
       # if it is defined in the type. Otherwise, +nil+.
+      #
+      # @return [OCI8::Metadata::TypeMethod or nil]
       def order_method
         __param(OCI_ATTR_ORDER_METHOD)
       end
 
-      # call-seq:
-      #   is_invoker_rights? -> boolean
-      #
       # Returns +true+ if the type has
       # {invoker's rights}[http://download.oracle.com/docs/cd/B28359_01/appdev.111/appdev.111/b28371/adobjdes.htm#ADOBJ00810].
       # Otherwise, +false+.
@@ -879,25 +807,20 @@
         attr_get_ub1(OCI_ATTR_IS_INVOKER_RIGHTS) != 0
       end
 
-      # call-seq:
-      #   name -> string
-      #
       # Returns the type name.
+      #
+      # @return [String]
       def name
         attr_get_string(OCI_ATTR_NAME)
       end
 
-      # call-seq:
-      #   schema_name -> string
-      #
       # Returns the schema name where the type has been created.
+      #
+      # @return [String]
       def schema_name
         attr_get_string(OCI_ATTR_SCHEMA_NAME)
       end
 
-      # call-seq:
-      #   is_final_type? -> boolean
-      #
       # Returns +true+ if the type is a
       # {final type}[http://download.oracle.com/docs/cd/B28359_01/appdev.111/b28371/adobjbas.htm#CIHFBHFC];
       # in other words, subtypes cannot be derived from the type.
@@ -906,9 +829,6 @@
         attr_get_ub1(OCI_ATTR_IS_FINAL_TYPE) != 0
       end
 
-      # call-seq:
-      #   is_instantiable_type? -> boolean
-      #
       # Returns +true+ if the type is not declared without
       # {<tt>NOT INSTANTIABLE</tt>}[http://download.oracle.com/docs/cd/B28359_01/appdev.111/b28371/adobjbas.htm#i456586].
       # Otherwise, +false+.
@@ -916,9 +836,6 @@
         attr_get_ub1(OCI_ATTR_IS_INSTANTIABLE_TYPE) != 0
       end
 
-      # call-seq:
-      #   is_subtype? -> boolean
-      #
       # Returns +true+ if the type is a
       # {subtype}[http://download.oracle.com/docs/cd/B28359_01/appdev.111/b28371/adobjbas.htm#BCFJJADG].
       # Otherwise, +false+.
@@ -926,36 +843,32 @@
         attr_get_ub1(OCI_ATTR_IS_SUBTYPE) != 0
       end
 
-      # call-seq:
-      #   supertype_schema_name -> string or nil
-      #
       # Returns the supertype's schema name if the type is a subtype.
       # Otherwise, +nil+.
+      #
+      # @return [String or nil]
       def supertype_schema_name
         attr_get_string(OCI_ATTR_SUPERTYPE_SCHEMA_NAME) if is_subtype?
       end
 
-      # call-seq:
-      #   supertype_name -> string or nil
-      #
       # Returns the supertype's name if the type is a subtype.
       # Otherwise, +nil+.
+      #
+      # @return [String or nil]
       def supertype_name
         attr_get_string(OCI_ATTR_SUPERTYPE_NAME) if is_subtype?
       end
 
-      # call-seq:
-      #   type_attrs -> list of attribute information
+      # Returns attribute information of the type.
       #
-      # Returns an array of OCI8::Metadata::TypeAttr which the type has.
+      # @return [array of OCI8::Metadata::TypeAttr]
       def type_attrs
         @type_attrs ||= list_type_attrs.to_a
       end
 
-      # call-seq:
-      #   type_methods -> list of method information
+      # Returns method information of the type.
       #
-      # Returns an array of OCI8::Metadata::TypeMethod which the type has.
+      # @return [array of OCI8::Metadata::TypeMethod]
       def type_methods
         @type_methods ||= list_type_methods.to_a
       end
@@ -1173,9 +1086,11 @@
         __boolean(OCI_ATTR_IS_OVERRIDING_METHOD)
       end
 
-      # array of TypeArgument objects.
+      # Returns argument information of the type method.
       #
       # The first element is the return type in case of Function.
+      #
+      # @return [array of OCI8::Metadata::Argument]
       def arguments
         @arguments ||= list_arguments.to_a
       end
@@ -1337,21 +1252,29 @@
       end
 
       # minimum value
+      #
+      # @return [Integer]
       def min
         attr_get_integer(OCI_ATTR_MIN)
       end
 
       # maximum value
+      #
+      # @return [Integer]
       def max
         attr_get_integer(OCI_ATTR_MAX)
       end
 
       # increment
+      #
+      # @return [Integer]
       def incr
         attr_get_integer(OCI_ATTR_INCR)
       end
 
       # number of sequence numbers cached; zero if the sequence is not a cached sequence.
+      #
+      # @return [Integer]
       def cache
         attr_get_integer(OCI_ATTR_CACHE)
       end
@@ -1362,6 +1285,8 @@
       end
 
       # high-water mark
+      #
+      # @return [Integer]
       def hw_mark
         attr_get_integer(OCI_ATTR_HW_MARK)
       end

Modified: trunk/ruby-oci8/lib/oci8/object.rb
===================================================================
--- trunk/ruby-oci8/lib/oci8/object.rb	2012-11-11 10:03:11 UTC (rev 539)
+++ trunk/ruby-oci8/lib/oci8/object.rb	2012-11-11 11:56:27 UTC (rev 540)
@@ -7,7 +7,7 @@
 
   # Returns the type descriptor object which correspond to the given class.
   #
-  # @param [class of an OCI8::Object::Base's subclass]
+  # @param [class of an OCI8::Object::Base's subclass] klass
   # @return [OCI8::TDO]
   #
   # @private
@@ -29,7 +29,7 @@
 
   # Returns the type descriptor object which correspond to the given metadata.
   #
-  # @param [OCI8::Metadata::Base's subclass]
+  # @param [OCI8::Metadata::Base's subclass] metadata
   # @return [OCI8::TDO]
   #
   # @private

Modified: trunk/ruby-oci8/lib/oci8/oci8.rb
===================================================================
--- trunk/ruby-oci8/lib/oci8/oci8.rb	2012-11-11 10:03:11 UTC (rev 539)
+++ trunk/ruby-oci8/lib/oci8/oci8.rb	2012-11-11 11:56:27 UTC (rev 540)
@@ -169,16 +169,18 @@
     @username = nil
   end
 
-  # call-seq:
-  #   parse(sql_text) -> an OCI8::Cursor
+  # Returns a prepared SQL handle.
   #
-  # Returns a prepared SQL handle.
+  # @param [String]  sql  SQL statement
+  # @return [OCI8::Cursor]
   def parse(sql)
     @last_error = nil
     parse_internal(sql)
   end
 
   # same with OCI8#parse except that this doesn't reset OCI8#last_error.
+  #
+  # @private
   def parse_internal(sql)
     cursor = OCI8::Cursor.new(self, sql)
     cursor.prefetch_rows = @prefetch_rows if @prefetch_rows
@@ -276,6 +278,8 @@
   end
 
   # same with OCI8#exec except that this doesn't reset OCI8#last_error.
+  #
+  # @private
   def exec_internal(sql, *bindvars)
     begin
       cursor = parse(sql)
@@ -308,9 +312,11 @@
     end
   end # exec
 
-  # :call-seq:
-  #   select_one(sql, *bindvars) -> first_one_row
+  # Executes a SQL statement and fetches the first one row.
   #
+  # @param [String] sql        SQL statement
+  # @param [Object] bindvars   bind variables
+  # @return [Array] an array of first row.
   def select_one(sql, *bindvars)
     cursor = self.parse(sql)
     begin
@@ -335,12 +341,11 @@
     "#<OCI8:#{username}>"
   end
 
-  # :call-seq:
-  #   oracle_server_version -> oraver
-  #
   # Returns an OCI8::OracleVersion of the Oracle server version.
   #
   # See also: OCI8.oracle_client_version
+  #
+  # @return [OCI8::OracleVersion]
   def oracle_server_version
     unless defined? @oracle_server_version
       if vernum = oracle_server_vernum
@@ -360,22 +365,18 @@
     @oracle_server_version
   end
 
-  # :call-seq:
-  #   database_charset_name -> string
+  # Returns the Oracle database character set name.
   #
-  # (new in 2.1.0)
-  #
-  # Returns the database character set name.
+  # @since 2.1.0
+  # @return [String] Oracle database character set name
   def database_charset_name
     charset_id2name(@server_handle.send(:attr_get_ub2, OCI_ATTR_CHARSET_ID))
   end
 
-  # :call-seq:
-  #   OCI8.client_charset_name -> string
+  # Returns the client-side Oracle character set name.
   #
-  # (new in 2.1.0)
-  #
-  # Returns the client character set name.
+  # @since 2.1.0
+  # @return [String] client-side character set name
   def self.client_charset_name
     @@client_charset_name
   end
@@ -470,6 +471,8 @@
 
 class Numeric
   # Converts +self+ to {OraNumber}.
+  #
+  # @return [OraNumber]
   def to_onum
     OraNumber.new(self)
   end
@@ -478,7 +481,7 @@
 class String # :nodoc:
 
   # Converts +self+ to {OraNumber}.
-  # Optional <i>fmt</i> and <i>nlsparam</i> is used as
+  # Optional <i>format</i> and <i>nls_params</i> is used as
   # {http://docs.oracle.com/cd/E11882_01/server.112/e17118/functions211.htm Oracle SQL function TO_NUMBER}
   # does.
   #
@@ -487,8 +490,8 @@
   #   '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
+  # @param [String] format
+  # @param [String] nls_params
   # @return [OraNumber]
   def to_onum(format = nil, nls_params = nil)
     OraNumber.new(self, format, nls_params)

Modified: trunk/ruby-oci8/lib/oci8.rb.in
===================================================================
--- trunk/ruby-oci8/lib/oci8.rb.in	2012-11-11 10:03:11 UTC (rev 539)
+++ trunk/ruby-oci8/lib/oci8.rb.in	2012-11-11 11:56:27 UTC (rev 540)
@@ -56,19 +56,24 @@
 require 'oci8/oracle_version.rb'
 
 class OCI8
+  # @private
   ORAVER_8_0  = OCI8::OracleVersion.new(8, 0)
+  # @private
   ORAVER_8_1  = OCI8::OracleVersion.new(8, 1)
+  # @private
   ORAVER_9_0  = OCI8::OracleVersion.new(9, 0)
+  # @private
   ORAVER_9_2  = OCI8::OracleVersion.new(9, 2)
+  # @private
   ORAVER_10_1 = OCI8::OracleVersion.new(10, 1)
+  # @private
   ORAVER_10_2 = OCI8::OracleVersion.new(10, 2)
+  # @private
   ORAVER_11_1 = OCI8::OracleVersion.new(11, 1)
 
+  # @private
   @@oracle_client_version = OCI8::OracleVersion.new(self.oracle_client_vernum)
 
-  # :call-seq:
-  #   OCI8.oracle_client_version -> oraver
-  #
   # Returns an OCI8::OracleVersion of the Oracle client version.
   #
   # If this library is configured without '--with-runtime-check',
@@ -82,11 +87,14 @@
   #
   # Otherwise, it is the version retrieved from an OCI function
   # OCIClientVersion().
+  #
+  # @return [OCI8::OracleVersion] Oracle client version
   def self.oracle_client_version
     @@oracle_client_version
   end
 
   # defined for backward compatibility.
+  # @private
   CLIENT_VERSION = @@oracle_client_version.major.to_s +
     @@oracle_client_version.minor.to_s +
     @@oracle_client_version.update.to_s



More information about the ruby-oci8-commit mailing list