Added documentation for database adapters to visible RDoc

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@771 5ecf4fe2-1ee6-0310-87b1-e25e094e27de

activerecord/lib/active_record/connection_adapters/mysql_adapter.rb

@@ -41,7 +41,22 @@ module ActiveRecord
   end
  
   module ConnectionAdapters
-    class MysqlAdapter < AbstractAdapter # :nodoc:
+    # The MySQL adapter will work with both Ruby/MySQL, which is a Ruby-based MySQL adapter that comes bundled with Active Record, and with
+    # the faster C-based MySQL/Ruby adapter (available both as a gem and from http://www.tmtm.org/en/mysql/ruby/).
+    #
+    # Options:
+    #
+    # * <tt>:host</tt> -- Defaults to localhost
+    # * <tt>:port</tt> -- Defaults to 3306
+    # * <tt>:socket</tt> -- Defaults to /tmp/mysql.sock
+    # * <tt>:username</tt> -- Defaults to root
+    # * <tt>:password</tt> -- Defaults to nothing
+    # * <tt>:database</tt> -- The name of the database. No default, must be provided.
+    # * <tt>:sslkey</tt> -- Necessary to use MySQL with an SSL connection
+    # * <tt>:sslcert</tt> -- Necessary to use MySQL with an SSL connection
+    # * <tt>:sslcapath</tt> -- Necessary to use MySQL with an SSL connection
+    # * <tt>:sslcipher</tt> -- Necessary to use MySQL with an SSL connection
+    class MysqlAdapter < AbstractAdapter
       LOST_CONNECTION_ERROR_MESSAGES = [ 
         "Server shutdown in progress",
         "Broken pipe", 

activerecord/lib/active_record/connection_adapters/oci_adapter.rb

@@ -1,8 +1,3 @@
-# This is an Oracle adapter for the ActiveRecord persistence framework. It relies upon the OCI8
-# driver, which works with Oracle 8i and above. It was developed on Windows 2000
-# against an 8i database, using ActiveRecord 1.6.0 and OCI8 0.1.9. It has also been tested against
-# a 9i database.
-#
 # Implementation notes:
 # 1.  I had to redefine a method in ActiveRecord to make it possible to implement an autonumbering
 #     solution for oracle. It's implemented in a way that is intended to not break other adapters.
@@ -17,23 +12,6 @@
 #     consistency with other adapters I've allowed the LIMIT and OFFSET clauses to be included in
 #     the sql string and later extracted them by parsing the string.
 #
-# Usage notes:
-# 1.  Key generation uses a sequence "rails_sequence" for all tables. (I couldn't find a simple
-#     and safe way of passing table-specific sequence information to the adapter.)
-# 2.  Oracle uses DATE or TIMESTAMP datatypes for both dates and times. Consequently I have had to
-#     resort to some hacks to get data converted to Date or Time in Ruby.
-#     If the column_name ends in _time it's created as a Ruby Time. Else if the
-#     hours/minutes/seconds are 0, I make it a Ruby Date. Else it's a Ruby Time.
-#     This is nasty - but if you use Duck Typing you'll probably not care very much.
-#     In 9i it's tempting to map DATE to Date and TIMESTAMP to Time but I don't think that is
-#     valid - too many databases use DATE for both.
-#     Timezones and sub-second precision on timestamps are not supported.
-# 3.  Default values that are functions (such as "SYSDATE") are not supported. This is a
-#     restriction of the way active record supports default values.
-# 4.  Referential integrity constraints are not fully supported. Under at least
-#     some circumstances, active record appears to delete parent and child records out of
-#     sequence and out of transaction scope. (Or this may just be a problem of test setup.)
-#
 # Do what you want with this code, at your own peril, but if any significant portion of my code
 # remains then please acknowledge my contribution.
 # Copyright 2005 Graham Jenkins
@@ -44,8 +22,8 @@ begin
   require_library_or_gem 'oci8' unless self.class.const_defined? :OCI8
 
   module ActiveRecord
-    module ConnectionAdapters
-      class OCIColumn < Column
+    module ConnectionAdapters #:nodoc:
+      class OCIColumn < Column #:nodoc:
         attr_reader :sql_type
 
         def initialize(name, default, limit, sql_type, scale)
@@ -92,6 +70,33 @@ begin
         end
       end
 
+      # This is an Oracle adapter for the ActiveRecord persistence framework. It relies upon the OCI8
+      # driver (http://rubyforge.org/projects/ruby-oci8/), which works with Oracle 8i and above. 
+      # It was developed on Windows 2000 against an 8i database, using ActiveRecord 1.6.0 and OCI8 0.1.9. 
+      # It has also been tested against a 9i database.
+      #
+      # Usage notes:
+      # * Key generation uses a sequence "rails_sequence" for all tables. (I couldn't find a simple
+      #   and safe way of passing table-specific sequence information to the adapter.)
+      # * Oracle uses DATE or TIMESTAMP datatypes for both dates and times. Consequently I have had to
+      #   resort to some hacks to get data converted to Date or Time in Ruby.
+      #   If the column_name ends in _time it's created as a Ruby Time. Else if the
+      #   hours/minutes/seconds are 0, I make it a Ruby Date. Else it's a Ruby Time.
+      #   This is nasty - but if you use Duck Typing you'll probably not care very much.
+      #   In 9i it's tempting to map DATE to Date and TIMESTAMP to Time but I don't think that is
+      #   valid - too many databases use DATE for both.
+      #   Timezones and sub-second precision on timestamps are not supported.
+      # * Default values that are functions (such as "SYSDATE") are not supported. This is a
+      #   restriction of the way active record supports default values.
+      # * Referential integrity constraints are not fully supported. Under at least
+      #   some circumstances, active record appears to delete parent and child records out of
+      #   sequence and out of transaction scope. (Or this may just be a problem of test setup.)
+      #
+      # Options:
+      #
+      # * <tt>:username</tt> -- Defaults to root
+      # * <tt>:password</tt> -- Defaults to nothing
+      # * <tt>:host</tt> -- Defaults to localhost
       class OCIAdapter < AbstractAdapter
         def quote_string(s)
           s.gsub /'/, "''"
@@ -202,7 +207,7 @@ begin
 
   module ActiveRecord
     class Base
-      def self.oci_connection(config)
+      def self.oci_connection(config) #:nodoc:
         conn = OCI8.new config[:username], config[:password], config[:host]
         conn.exec %q{alter session set nls_date_format = 'YYYY-MM-DD HH24:MI:SS'}
         conn.exec %q{alter session set nls_timestamp_format = 'YYYY-MM-DD HH24:MI:SS'}
@@ -214,7 +219,7 @@ begin
       # Enable the id column to be bound into the sql later, by the adapter's insert method.
       # This is preferable to inserting the hard-coded value here, because the insert method
       # needs to know the id value explicitly.
-      def attributes_with_quotes(creating = true)
+      def attributes_with_quotes(creating = true) #:nodoc:
         aq = attributes_with_quotes_pre_oci creating
         if connection.class == ConnectionAdapters::OCIAdapter
           aq[self.class.primary_key] = ":id" if creating && aq[self.class.primary_key].nil?
@@ -225,7 +230,7 @@ begin
       after_save :write_lobs
 
       # After setting large objects to empty, select the OCI8::LOB and write back the data
-      def write_lobs()
+      def write_lobs() #:nodoc:
         if connection.class == ConnectionAdapters::OCIAdapter
           self.class.columns.select { |c| c.type == :binary }.each { |c|
             break unless value = self[c.name]
@@ -242,8 +247,8 @@ begin
     end
   end
 
-  class OCI8
-    class Cursor
+  class OCI8 #:nodoc:
+    class Cursor #:nodoc:
       alias :define_a_column_pre_ar :define_a_column
       def define_a_column(i)
         case do_ocicall(@ctx) { @parms[i - 1].attrGet(OCI_ATTR_DATA_TYPE) }

activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb

@@ -43,8 +43,18 @@ module ActiveRecord
   end
 
   module ConnectionAdapters
-
-    class PostgreSQLAdapter < AbstractAdapter # :nodoc:
+    # The PostgreSQL adapter works both with the C-based (http://www.postgresql.jp/interfaces/ruby/) and the Ruby-base
+    # (available both as gem and from http://rubyforge.org/frs/?group_id=234&release_id=1145) drivers.
+    #
+    # Options:
+    #
+    # * <tt>:host</tt> -- Defaults to localhost
+    # * <tt>:port</tt> -- Defaults to 5432
+    # * <tt>:username</tt> -- Defaults to nothing
+    # * <tt>:password</tt> -- Defaults to nothing
+    # * <tt>:database</tt> -- The name of the database. No default, must be provided.
+    # * <tt>:schema_order</tt> -- An optional schema order string that is using in a SET search_path TO <schema_order> call on connection.
+    class PostgreSQLAdapter < AbstractAdapter
       def select_all(sql, name = nil)
         select(sql, name)
       end

activerecord/lib/active_record/connection_adapters/sqlite_adapter.rb

@@ -59,9 +59,8 @@ module ActiveRecord
     end
   end
 
-  module ConnectionAdapters
-    
-    class SQLiteColumn < Column
+  module ConnectionAdapters #:nodoc:
+    class SQLiteColumn < Column #:nodoc:
       def string_to_binary(value)
         value.gsub(/(\0|\%)/) do
           case $1
@@ -81,7 +80,13 @@ module ActiveRecord
       end
     end
 
-    class SQLiteAdapter < AbstractAdapter # :nodoc:
+    # The SQLite adapter works with both the 2.x and 3.x series of SQLite with the sqlite-ruby drivers (available both as gems and
+    # from http://rubyforge.org/projects/sqlite-ruby/).
+    #
+    # Options:
+    #
+    # * <tt>:dbfile</tt> -- Path to the database file.
+    class SQLiteAdapter < AbstractAdapter
       def execute(sql, name = nil)
         log(sql, name) { @connection.execute(sql) }
       end

activerecord/lib/active_record/connection_adapters/sqlserver_adapter.rb

@@ -5,24 +5,6 @@ require 'active_record/connection_adapters/abstract_adapter'
 # Author: Joey Gibson <joey@joeygibson.com>
 # Date:   10/14/2004
 #
-# REQUIREMENTS:
-#
-# This adapter will ONLY work on Windows systems, since it relies on Win32OLE, which,
-# to my knowledge, is only available on Window.
-#
-# It relies on the ADO support in the DBI module. If you are using the
-# one-click installer of Ruby, then you already have DBI installed, but
-# the ADO module is *NOT* installed. You will need to get the latest
-# source distribution of Ruby-DBI from http://ruby-dbi.sourceforge.net/
-# unzip it, and copy the file src/lib/dbd_ado/ADO.rb to
-# X:/Ruby/lib/ruby/site_ruby/1.8/DBD/ADO/ADO.rb (you will need to create
-# the ADO directory). Once you've installed that file, you are ready to go.
-#
-# This module uses the ADO-style DSNs for connection. For example:
-# "DBI:ADO:Provider=SQLOLEDB;Data Source=(local);Initial Catalog=test;User Id=sa;Password=password;"
-# with User Id replaced with your proper login, and Password with your
-# password.
-#
 # I have tested this code on a WindowsXP Pro SP1 system,
 # ruby 1.8.2 (2004-07-29) [i386-mswin32], SQL Server 2000.
 #
@@ -128,8 +110,24 @@ module ActiveRecord
 
     end
 
-    class SQLServerAdapter < AbstractAdapter # :nodoc:
-
+    # This adapter will ONLY work on Windows systems, since it relies on Win32OLE, which,
+    # to my knowledge, is only available on Window.
+    #
+    # It relies on the ADO support in the DBI module. If you are using the
+    # one-click installer of Ruby, then you already have DBI installed, but
+    # the ADO module is *NOT* installed. You will need to get the latest
+    # source distribution of Ruby-DBI from http://ruby-dbi.sourceforge.net/
+    # unzip it, and copy the file <tt>src/lib/dbd_ado/ADO.rb</tt> to
+    # <tt>X:/Ruby/lib/ruby/site_ruby/1.8/DBD/ADO/ADO.rb</tt> (you will need to create
+    # the ADO directory). Once you've installed that file, you are ready to go.
+    #
+    # Options:
+    #
+    # * <tt>:host</tt> -- Defaults to localhost
+    # * <tt>:username</tt> -- Defaults to sa
+    # * <tt>:password</tt> -- Defaults to nothing
+    # * <tt>:database</tt> -- The name of the database. No default, must be provided.
+    class SQLServerAdapter < AbstractAdapter
       def select_all(sql, name = nil)
         add_limit!(sql, nil)
         select(sql, name)