lib/rom/sql/gateway.rb in rom-sql-1.0.0.beta3 vs lib/rom/sql/gateway.rb in rom-sql-1.0.0.rc1

@@ -10,58 +10,83 @@
 
 module ROM
   module SQL
     # SQL gateway
     #
-    # @example
-    #   db = Sequel.connect(:sqlite)
-    #   gateway = ROM::SQL::Gateway.new(db)
-    #
-    #   users = gateway.dataset(:users)
-    #
     # @api public
     class Gateway < ROM::Gateway
       include Dry::Core::Constants
       include Migration
 
       class << self
+        # FIXME: get rid of this and figure out a nicer way of handling migration DSL
+        # we want to have global access ONLY when running migration tasks
         attr_accessor :instance
       end
 
       CONNECTION_EXTENSIONS = {
         postgres: %i(pg_array pg_json pg_enum)
       }.freeze
 
-      # Return optionally configured logger
-      #
-      # @return [Object] logger
-      #
-      # @api public
+      # @!attribute [r] logger
+      #   @return [Object] configured gateway logger
       attr_reader :logger
 
-      # @api private
+      # @!attribute [r] options
+      #   @return [Hash] Options used for connection
       attr_reader :options
 
-      # SQL gateway interface
+      # Initialize an SQL gateway
       #
-      # @overload connect(uri, options)
-      #   Connects to database via uri passing options
+      # Gateways are typically initialized via ROM::Configuration object, gateway constructor
+      # arguments such as URI and options are passed directly to this constructor
       #
+      # @overload initialize(uri)
+      #   Connects to a database via URI
+      #
+      #   @example
+      #     ROM.container(:sql, 'postgres://localhost/db_name')
+      #
+      #   @param [Sequel::Database] connection a connection instance
+      #
+      # @overload initialize(uri, options)
+      #   Connects to a database via URI and options
+      #
+      #   @example
+      #     ROM.container(:sql, 'postgres://localhost/db_name', extensions: %w[pg_enum])
+      #
       #   @param [String,Symbol] uri connection URI
+      #
       #   @param [Hash] options connection options
       #
-      # @overload connect(connection)
-      #   Re-uses connection instance
+      #   @option options [Array<Symbol>] :inferrable_relations
+      #     A list of dataset names that should be inferred. If
+      #     this is set explicitly to an empty array relations
+      #     won't be inferred at all
       #
+      #   @option options [Array<Symbol>] :not_inferrable_relations
+      #     A list of dataset names that should NOT be inferred
+      #
+      #   @option options [Array<Symbol>] :extensions
+      #     A list of connection extensions supported by Sequel
+      #
+      #   @option options [String] :user Database username
+      #
+      #   @option options [String] :password Database password
+      #
+      # @overload initialize(connection)
+      #   Creates a gateway from an existing database connection. This
+      #   works with Sequel connections exclusively.
+      #
+      #   @example
+      #     ROM.container(:sql, Sequel.connect(:sqlite))
+      #
       #   @param [Sequel::Database] connection a connection instance
       #
-      # @example
-      #   gateway = ROM::SQL::Gateway.new('postgres://localhost/rom')
+      # @return [SQL::Gateway]
       #
-      #   # or reuse connection
-      #   DB = Sequel.connect('postgres://localhost/rom')
-      #   gateway = ROM::SQL::Gateway.new(DB)
+      # @see https://github.com/jeremyevans/sequel/blob/master/doc/opening_databases.rdoc Sequel connection docs
       #
       # @api public
       def initialize(uri, options = EMPTY_HASH)
         @connection = connect(uri, options)
         load_extensions(Array(options[:extensions]))
@@ -71,30 +96,41 @@
         super
 
         self.class.instance = self
       end
 
-      # Disconnect from database
+      # Disconnect from the gateway's database
       #
       # @api public
       def disconnect
         connection.disconnect
       end
 
       # Return dataset with the given name
       #
-      # @param [String] name dataset name
+      # Thsi returns a raw Sequel database
       #
+      # @param [String, Symbol] name The dataset name
+      #
       # @return [Dataset]
       #
       # @api public
       def [](name)
         connection[name]
       end
 
       # Setup a logger
       #
+      # @example set a logger during configuration process
+      #   rom = ROM.container(:sql, 'sqlite::memory') do |config|
+      #     config.gateways[:default].use_logger(Logger.new($stdout))
+      #   end
+      #
+      # @example set logger after gateway has been established
+      #   rom = ROM.container(:sql, 'sqlite::memory')
+      #   rom.gateways[:default].use_logger(Logger.new($stdout))
+      #
       # @param [Object] logger
       #
       # @see Sequel::Database#loggers
       #
       # @api public
@@ -112,22 +148,22 @@
       # @api public
       def dataset(name)
         connection[name]
       end
 
-      # Check if dataset exists
+      # Check if a dataset exists
       #
       # @param [String] name dataset name
       #
       # @api public
       def dataset?(name)
         schema.include?(name)
       end
 
-      # Extend database-specific behavior
+      # Extend the command class with database-specific behavior
       #
-      # @param [Class] klass command class
-      # @param [Object] dataset a dataset that will be used
+      # @param [Class] klass Command class
+      # @param [Sequel::Dataset] dataset A dataset that will be used
       #
       # Note: Currently, only postgres is supported.
       #
       # @api public
       def extend_command_class(klass, dataset)