rom-core 4.0.0.beta3 → 4.0.0.rc1

data/lib/rom/associations/one_to_many.rb

@@ -2,17 +2,35 @@ require 'rom/associations/abstract'
 
 module ROM
   module Associations
+    # Abstract one-to-many association
+    #
+    # @api public
     class OneToMany < Abstract
+      # Adapters must implement this method
+      #
+      # @abstract
+      #
       # @api public
       def call(*)
         raise NotImplementedError
       end
 
+      # Return configured or inferred FK name
+      #
+      # @return [Symbol]
+      #
       # @api public
       def foreign_key
         definition.foreign_key || target.foreign_key(source.name)
       end
 
+      # Associate child tuple with a parent
+      #
+      # @param [Hash] child The child tuple
+      # @param [Hash] parent The parent tuple
+      #
+      # @return [Hash]
+      #
       # @api private
       def associate(child, parent)
         pk, fk = join_key_map
@@ -21,11 +39,19 @@ module ROM
 
       protected
 
+      # Return primary key on the source side
+      #
+      # @return [Symbol]
+      #
       # @api protected
       def source_key
         source.schema.primary_key_name
       end
 
+      # Return foreign key name on the target side
+      #
+      # @return [Symbol]
+      #
       # @api protected
       def target_key
         foreign_key

data/lib/rom/associations/one_to_one.rb

@@ -2,6 +2,9 @@ require 'rom/associations/one_to_many'
 
 module ROM
   module Associations
+    # Abstract one-to-one association type
+    #
+    # @api public
     class OneToOne < OneToMany
     end
   end

data/lib/rom/associations/one_to_one_through.rb

@@ -2,6 +2,9 @@ require 'rom/associations/many_to_many'
 
 module ROM
   module Associations
+    # Abstract one-to-one-through association type
+    #
+    # @api public
     class OneToOneThrough < ManyToMany
     end
   end

data/lib/rom/attribute.rb

@@ -20,7 +20,7 @@ module ROM
     extend Initializer
 
     # @!attribute [r] type
-    #   @return [Dry::Types::Definition, Dry::Types::Sum, Dry::Types::Constrained]
+    #   @return [Dry::Types::Definition, Dry::Types::Sum, Dry::Types::Constrained] The attribute's type object
     param :type
 
     # @api private
@@ -336,7 +336,7 @@ module ROM
 
     # Check if the attribute type is equal to another
     #
-    # @param [Dry::Type, Attribute]
+    # @param [Dry::Type, Attribute] other
     #
     # @return [TrueClass,FalseClass]
     #

data/lib/rom/auto_curry.rb

@@ -1,4 +1,7 @@
 module ROM
+  # Relation extension which provides auto-currying of relation view methods
+  #
+  # @api private
   module AutoCurry
     def self.extended(klass)
       klass.define_singleton_method(:method_added) do |name|
@@ -8,6 +11,7 @@ module ROM
       end
     end
 
+    # @api private
     def auto_curry_guard
       @__auto_curry_busy__ = true
       yield
@@ -15,14 +19,21 @@ module ROM
       @__auto_curry_busy__ = false
     end
 
+    # @api private
     def auto_curry_busy?
       @__auto_curry_busy__ ||= false
     end
 
+    # @api private
     def auto_curried_methods
       @__auto_curried_methods__ ||= Set.new
     end
 
+    # Auto-curry a method
+    #
+    # @param [Symbol] name The name of a method
+    #
+    # @api private
     def auto_curry(name, &block)
       arity = instance_method(name).arity
 

data/lib/rom/cache.rb

@@ -1,27 +1,45 @@
 require 'concurrent/map'
 
 module ROM
+  # Thread-safe cache used by various rom components
+  #
   # @api private
   class Cache
     attr_reader :objects
 
+    # @api private
     class Namespaced
+      # @api private
       attr_reader :cache
 
+      # @api private
       attr_reader :namespace
 
+      # @api private
       def initialize(cache, namespace)
         @cache = cache
         @namespace = namespace.to_sym
       end
 
+      # @api private
       def [](key)
         cache[[namespace, key].hash]
       end
 
+      # @api private
       def fetch_or_store(*args, &block)
         cache.fetch_or_store([namespace, args.hash].hash, &block)
       end
+
+      # @api private
+      def size
+        cache.size
+      end
+
+      # @api private
+      def inspect
+        %(#<#{self.class} size=#{size}>)
+      end
     end
 
     # @api private
@@ -39,8 +57,19 @@ module ROM
       objects.fetch_or_store(args.hash, &block)
     end
 
+    # @api private
+    def size
+      objects.size
+    end
+
+    # @api private
     def namespaced(namespace)
       @namespaced[namespace] ||= Namespaced.new(objects, namespace)
     end
+
+    # @api private
+    def inspect
+      %(#<#{self.class} size=#{size} namespaced=#{@namespaced.inspect}>)
+    end
   end
 end

data/lib/rom/command_compiler.rb

@@ -23,15 +23,15 @@ module ROM
     end
 
     # @!attribute [r] gateways
-    #   @return [ROM::Registry]
+    #   @return [ROM::Registry] Gateways used for command extensions
     param :gateways
 
     # @!attribute [r] relations
-    #   @return [ROM::RelationRegistry]
+    #   @return [ROM::RelationRegistry] Relations used with a given compiler
     param :relations
 
-    # @!attribute [r] relations
-    #   @return [ROM::Registry]
+    # @!attribute [r] commands
+    #   @return [ROM::Registry] Command registries with custom commands
     param :commands
 
     # @!attribute [r] notifications

data/lib/rom/command_registry.rb

@@ -15,19 +15,23 @@ module ROM
     # @api private
     param :elements
 
-    # Name of the relation from which commands are under
-    #
-    # @return [String]
-    #
-    # @api private
+    # @!attribute [r] relation_name
+    #   @return [Relation::Name] The name of a relation
     option :relation_name
 
+    # @!attribute [r] mappers
+    #   @return [MapperRegistry] Optional mapper registry
     option :mappers, optional: true
 
+    # @!attribute [r] mapper
+    #   @return [Object#call] Default mapper for processing command results
     option :mapper, optional: true
 
+    # @!attribute [r] compiler
+    #   @return [CommandCompiler] A command compiler instance
     option :compiler, optional: true
 
+    # @api private
     def self.element_not_found_error
       CommandNotFoundError
     end

data/lib/rom/commands/class_interface.rb

@@ -75,12 +75,12 @@ module ROM
 
       # Create a command class with a specific type
       #
-      # @param [Symbol] command name
-      # @param [Class] parent class
+      # @param [Symbol] name Command name
+      # @param [Class] type Command class
       #
-      # @yield [Class] create class
+      # @yield [Class]
       #
-      # @return [Class, Object] return result of the block if it was provided
+      # @return [Class, Object]
       #
       # @api public
       def create_class(name, type, &block)
@@ -105,8 +105,8 @@ module ROM
       #   end
       #
       # @param [Symbol] plugin
-      # @param [Hash] options
-      # @option options [Symbol] :adapter (:default) first adapter to check for plugin
+      # @param [Hash] _options
+      # @option _options [Symbol] :adapter (:default) first adapter to check for plugin
       #
       # @api public
       def use(plugin, _options = EMPTY_HASH)
@@ -115,7 +115,7 @@ module ROM
 
       # Extend a command class with relation view methods
       #
-      # @param [Relation]
+      # @param [Relation] relation
       #
       # @return [Class]
       #

data/lib/rom/commands/graph/input_evaluator.rb

@@ -1,19 +1,37 @@
 module ROM
   module Commands
     class Graph
+      # Evaluator for lazy commands which extracts values for commands from nested hashes
+      #
+      # @api private
       class InputEvaluator
         include Dry::Equalizer(:tuple_path, :excluded_keys)
 
+        # @!attribute [r] tuple_path
+        #   @return [Array<Symbol>] A list of keys pointing to a value inside a hash
         attr_reader :tuple_path
 
+        # @!attribute [r] excluded_keys
+        #   @return [Array<Symbol>] A list of keys that should be excluded
         attr_reader :excluded_keys
 
+        # @!attribute [r] exclude_proc
+        #   @return [Array<Symbol>] A function that should determine which keys should be excluded
         attr_reader :exclude_proc
 
+        # Build an input evaluator
+        #
+        # @param [Array<Symbol>] tuple_path The tuple path
+        # @param [Array] nodes
+        #
+        # @return [InputEvaluator]
+        #
+        # @api private
         def self.build(tuple_path, nodes)
           new(tuple_path, extract_excluded_keys(nodes))
         end
 
+        # @api private
         def self.extract_excluded_keys(nodes)
           return unless nodes
 
@@ -24,19 +42,31 @@ module ROM
             .reject { |item| item.is_a?(Array) }
         end
 
+        # Return default exclude_proc
+        #
+        # @api private
         def self.exclude_proc(excluded_keys)
           -> input { input.reject { |k, _| excluded_keys.include?(k) } }
         end
 
+        # Initialize a new input evaluator
+        #
+        # @return [InputEvaluator]
+        #
+        # @api private
         def initialize(tuple_path, excluded_keys)
           @tuple_path = tuple_path
           @excluded_keys = excluded_keys
           @exclude_proc = self.class.exclude_proc(excluded_keys)
         end
 
-        def call(*args)
-          input, index = args
-
+        # Evaluate input hash
+        #
+        # @param [Hash] input The input hash
+        # @param [Integer] index Optional index
+        #
+        # @return [Hash]
+        def call(input, index = nil)
           value =
             begin
               if index

data/lib/rom/commands/lazy.rb

@@ -57,8 +57,12 @@ module ROM
         Composite.new(self, other)
       end
 
+      # Combine with other lazy commands
+      #
       # @see Abstract#combine
       #
+      # @return [Graph]
+      #
       # @api public
       def combine(*others)
         Graph.new(self, others)

data/lib/rom/commands/lazy/create.rb

@@ -1,7 +1,17 @@
 module ROM
   module Commands
     class Lazy
+      # Lazy command wrapper for create commands
+      #
+      # @api public
       class Create < Lazy
+        # Execute a command
+        #
+        # @see Command::Create#call
+        #
+        # @return [Hash,Array<Hash>]
+        #
+        # @api public
         def call(*args)
           first = args.first
           last = args.last

data/lib/rom/commands/lazy/delete.rb

@@ -1,7 +1,17 @@
 module ROM
   module Commands
     class Lazy
+      # Lazy command wrapper for delete commands
+      #
+      # @api public
       class Delete < Lazy
+        # Execute a lazy delete command
+        #
+        # @see Commands::Delete#call
+        #
+        # @return [Hash, Array<Hash>]
+        #
+        # @api public
         def call(*args)
           first = args.first
           last = args.last

data/lib/rom/commands/lazy/update.rb

@@ -1,7 +1,17 @@
 module ROM
   module Commands
     class Lazy
+      # Lazy command wrapper for update commands
+      #
+      # @api public
       class Update < Lazy
+        # Execute a lazy update command
+        #
+        # @see Commands::Update#call
+        #
+        # @return [Hash, Array<Hash>]
+        #
+        # @api public
         def call(*args)
           first = args.first
           last = args.last

data/lib/rom/configuration.rb

@@ -22,7 +22,17 @@ module ROM
 
     NoDefaultAdapterError = Class.new(StandardError)
 
-    attr_reader :environment, :setup, :notifications
+    # @!attribute [r] environment
+    #   @return [Environment] Environment object with gateways
+    attr_reader :environment
+
+    # @!attribute [r] setup
+    #   @return [Setup] Setup object which collects component classes and plugins
+    attr_reader :setup
+
+    # @!attribute [r] notifications
+    #   @return [Notifications] Notification bus instance
+    attr_reader :notifications
 
     def_delegators :@setup, :register_relation, :register_command, :register_mapper, :register_plugin,
                             :command_classes, :mapper_classes,
@@ -30,7 +40,13 @@ module ROM
 
     def_delegators :@environment, :gateways, :gateways_map, :configure, :config
 
-    # @api public
+    # Initialize a new configuration
+    #
+    # @see Environment#initialize
+    #
+    # @return [Configuration]
+    #
+    # @api private
     def initialize(*args, &block)
       @environment = Environment.new(*args)
       @notifications = Notifications.event_bus(:configuration)
@@ -38,13 +54,15 @@ module ROM
 
       use :mappers # enable mappers by default
 
-      block.call(self) unless block.nil?
+      block.call(self) if block
     end
 
     # Apply a plugin to the configuration
     #
-    # @param [Mixed] The plugin identifier, usually a Symbol
-    # @param [Hash] Plugin options
+    # @param [Mixed] plugin The plugin identifier, usually a Symbol
+    # @param [Hash] options Plugin options
+    #
+    # @return [Configuration]
     #
     # @api public
     def use(plugin, options = {})
@@ -68,15 +86,6 @@ module ROM
       gateways.fetch(name)
     end
 
-    # Returns gateway if method is a name of a registered gateway
-    #
-    # @return [Gateway]
-    #
-    # @api private
-    def method_missing(name, *)
-      gateways.fetch(name) { super }
-    end
-
     # Hook for respond_to? used internally
     #
     # @api private
@@ -110,5 +119,16 @@ module ROM
     def default_adapter
       @default_adapter ||= adapter_for_gateway(default_gateway) || ROM.adapters.keys.first
     end
+
+    private
+
+    # Returns gateway if method is a name of a registered gateway
+    #
+    # @return [Gateway]
+    #
+    # @api private
+    def method_missing(name, *)
+      gateways.fetch(name) { super }
+    end
   end
 end