rom-core 4.0.0.beta3 → 4.0.0.rc1

data/lib/rom/relation/loaded.rb

@@ -2,7 +2,9 @@ require 'dry/equalizer'
 
 module ROM
   class Relation
-    # Materializes a relation and exposes interface to access the data
+    # Materializes a relation and exposes interface to access the data.
+    #
+    # This relation type is returned when a lazy relation is called
     #
     # @api public
     class Loaded
@@ -41,8 +43,8 @@ module ROM
       # @yield [Hash]
       #
       # @api public
-      def each(&block)
-        return to_enum unless block
+      def each
+        return to_enum unless block_given?
         collection.each { |tuple| yield(tuple) }
       end
 
@@ -86,7 +88,8 @@ module ROM
       # @param [Symbol] key The key name
       #
       # @return [Array]
-      # @raises KeyError when provided key doesn't exist in any of the tuples
+      #
+      # @raise KeyError when provided key doesn't exist in any of the tuples
       #
       # @api public
       def pluck(key)

data/lib/rom/relation/materializable.rb

@@ -19,8 +19,8 @@ module ROM
       # @yield [Hash,Object]
       #
       # @api public
-      def each(&block)
-        return to_enum unless block
+      def each
+        return to_enum unless block_given?
         to_a.each { |tuple| yield(tuple) }
       end
 

data/lib/rom/relation/view_dsl.rb

@@ -4,7 +4,8 @@ module ROM
     #
     # This is used to establish pre-defined relation views with explicit schemas.
     # Such views can be used to compose relations together, even from multiple
-    # adapters.
+    # adapters. In advanced adapters like rom-sql using view DSL is not required though,
+    # as relation schemas are dynamic and they always represent current tuple structure.
     #
     # @api public
     class ViewDSL

data/lib/rom/relation/wrap.rb

@@ -7,13 +7,23 @@ module ROM
     #
     # @api public
     class Wrap < Graph
+      # Wrap more relations
+      #
+      # @see Relation#wrap
+      #
+      # @return [Wrap]
+      #
       # @api public
       def wrap(*args)
         self.class.new(root, nodes + root.wrap(*args).nodes)
       end
 
+      # Materialize a wrap
+      #
       # @see Relation#call
       #
+      # @return [Loaded]
+      #
       # @api public
       def call(*args)
         if auto_map?
@@ -23,6 +33,10 @@ module ROM
         end
       end
 
+      # Return an adapter-specific relation representing a wrap
+      #
+      # @abstract
+      #
       # @api private
       def relation
         raise NotImplementedError

data/lib/rom/relation_registry.rb

@@ -1,7 +1,9 @@
 require 'rom/registry'
 
 module ROM
+  # @api private
   class RelationRegistry < Registry
+    # @api private
     def initialize(elements = {}, options = {})
       super
       yield(self, elements) if block_given?

data/lib/rom/schema.rb

@@ -85,6 +85,10 @@ module ROM
     # @api private
     option :relations, default: -> { EMPTY_HASH }
 
+    # @!attribute [r] canonical
+    #   @return [Symbol] The canonical schema which is carried in all schema instances
+    option :canonical, default: -> { self }
+
     # @api private
     option :attr_class, default: -> { Attribute }
 
@@ -137,7 +141,7 @@ module ROM
     #
     # Default implementation is a no-op and it simply returns back untouched relation
     #
-    # @param [Relation]
+    # @param [Relation] relation
     #
     # @return [Relation]
     #
@@ -293,7 +297,7 @@ module ROM
     #
     # This returns a new schema instance
     #
-    # @param [*Array<Attribute>]
+    # @param [Array<Attribute>] new_attributes
     #
     # @return [Schema]
     #
@@ -304,8 +308,6 @@ module ROM
 
     # Return a new schema with uniq attributes
     #
-    # @param [*Array<Attribute>]
-    #
     # @return [Schema]
     #
     # @api public
@@ -328,6 +330,19 @@ module ROM
       ! attributes.detect { |attr| attr.name == name }.nil?
     end
 
+    # Return if a schema is canonical
+    #
+    # @return [Boolean]
+    #
+    # @api public
+    def canonical?
+      self.equal?(canonical)
+    end
+
+    # Finalize a schema
+    #
+    # @return [self]
+    #
     # @api private
     def finalize!(**opts)
       return self if frozen?
@@ -352,6 +367,12 @@ module ROM
       self
     end
 
+    # Finalize associations defined in a schema
+    #
+    # @param [RelationRegistry] relations
+    #
+    # @return [self]
+    #
     # @api private
     def finalize_associations!(relations:)
       set!(:associations, yield) if associations.any?

data/lib/rom/schema/associations_dsl.rb

@@ -30,16 +30,25 @@ module ROM
       # @example using relation identifier
       #   has_many :tasks
       #
+      # @example setting custom foreign key name
+      #   has_many :tasks, foreign_key: :assignee_id
+      #
       # @example with a :through option
       #   # this establishes many-to-many association
       #   has_many :tasks, through: :users_tasks
       #
+      # @example using a custom view which overrides default one
+      #   has_many :posts, view: :published, override: true
+      #
       # @example using aliased association with a custom view
       #   has_many :posts, as: :published_posts, view: :published
       #
       # @example using custom target relation
       #   has_many :user_posts, relation: :posts
       #
+      # @example using custom target relation and an alias
+      #   has_many :user_posts, relation: :posts, as: :published, view: :published
+      #
       # @param [Symbol] target The target relation identifier
       # @param [Hash] options A hash with additional options
       #

data/lib/rom/schema/dsl.rb

@@ -5,10 +5,9 @@ require 'rom/attribute'
 require 'rom/schema/associations_dsl'
 
 module ROM
-  # Relation schema
-  #
-  # @api public
   class Schema
+    # Schema DSL exposed as `schema { .. }` in relation classes
+    #
     # @api public
     class DSL < BasicObject
       KERNEL_METHODS = %i(extend method).freeze
@@ -16,17 +15,41 @@ module ROM
 
       extend Initializer
 
+      # @!attribute [r] relation
+      #   @return [Relation::Name] The name of the schema's relation
       param :relation
 
+      # @!attribute [r] inferrer
+      #   @return [Inferrer] Optional attribute inferrer
       option :inferrer, default: -> { DEFAULT_INFERRER }
 
+      # @!attribute [r] schema_class
+      #   @return [Class] Schema class that should be instantiated
       option :schema_class, default: -> { Schema }
 
+      # @!attribute [r] attr_class
+      #   @return [Class] Attribute class that should be used
       option :attr_class, default: -> { Attribute }
 
+      # @!attribute [r] adapter
+      #   @return [Symbol] The adapter identifier used in gateways
       option :adapter, default: -> { :default }
 
-      attr_reader :attributes, :plugins, :definition, :associations_dsl
+      # @!attribute [r] attributes
+      #   @return [Hash] A hash with attributes defined by the DSL
+      attr_reader :attributes
+
+      # @!attribute [r] plugins
+      #   @return [Hash] A hash with schema plugins enabled in a schema
+      attr_reader :plugins
+
+      # @!attribute [r] definition
+      #   @return [Proc] Definition block passed to DSL
+      attr_reader :definition
+
+      # @!attribute [r] associations_dsl
+      #   @return [AssociationDSL] Associations defined within a block
+      attr_reader :associations_dsl
 
       # @api private
       def initialize(*, &block)

data/lib/rom/setup.rb

@@ -1,6 +1,9 @@
 require 'rom/setup/auto_registration'
 
 module ROM
+  # Setup objects collect component classes during setup/finalization process
+  #
+  # @api public
   class Setup
     # @return [Array] registered relation subclasses
     #
@@ -32,6 +35,23 @@ module ROM
       @notifications = notifications
     end
 
+    # Enable auto-registration for a given setup object
+    #
+    # @param [String, Pathname] directory The root path to components
+    # @param [Hash] options
+    # @option options [Boolean, String] :namespace Enable/disable namespace or provide a custom namespace name
+    #
+    # @return [Setup]
+    #
+    # @api public
+    def auto_registration(directory, options = {})
+      auto_registration = AutoRegistration.new(directory, options)
+      auto_registration.relations.map { |r| register_relation(r) }
+      auto_registration.commands.map { |r| register_command(r) }
+      auto_registration.mappers.map { |r| register_mapper(r) }
+      self
+    end
+
     # Relation sub-classes are being registered with this method during setup
     #
     # @api private
@@ -57,12 +77,5 @@ module ROM
     def register_plugin(plugin)
       plugins << plugin
     end
-
-    def auto_registration(directory, options = {})
-      auto_registration = AutoRegistration.new(directory, options)
-      auto_registration.relations.map { |r| register_relation(r) }
-      auto_registration.commands.map { |r| register_command(r) }
-      auto_registration.mappers.map { |r| register_mapper(r) }
-    end
   end
 end

data/lib/rom/setup/auto_registration.rb

@@ -9,23 +9,38 @@ require 'rom/setup/auto_registration_strategies/with_namespace'
 require 'rom/setup/auto_registration_strategies/custom_namespace'
 
 module ROM
+  # AutoRegistration is used to load component files automatically from the provided directory path
+  #
+  # @api public
   class AutoRegistration
     extend Initializer
 
     NamespaceType = Types::Strict::Bool | Types::Strict::String
+
     PathnameType = Types.Constructor(Pathname, &Kernel.method(:Pathname))
+
     DEFAULT_MAPPING = {
       relations: :relations,
       mappers: :mappers,
       commands: :commands
     }.freeze
 
+    # @!attribute [r] directory
+    #   @return [Pathname] The root path
     param :directory, type: PathnameType
 
+    # @!attribute [r] namespace
+    #   @return [Boolean,String]
+    #     The name of the top level namespace or true/false which
+    #     enables/disables default top level namespace inferred from the dir name
     option :namespace, type: NamespaceType, default: -> { true }
 
+    # @!attribute [r] component_dirs
+    #   @return [Hash] component => dir-name map
     option :component_dirs, type: Types::Strict::Hash, default: -> { DEFAULT_MAPPING }
 
+    # @!attribute [r] globs
+    #   @return [Hash] File globbing functions for each component dir
     option :globs, default: -> {
       Hash[
         component_dirs.map { |component, path|
@@ -34,20 +49,32 @@ module ROM
       ]
     }
 
+    # Load relation files
+    #
+    # @api private
     def relations
       load_entities(:relations)
     end
 
+    # Load command files
+    #
+    # @api private
     def commands
       load_entities(:commands)
     end
 
+    # Load mapper files
+    #
+    # @api private
     def mappers
       load_entities(:mappers)
     end
 
     private
 
+    # Load given component files
+    #
+    # @api private
     def load_entities(entity)
       Dir[globs[entity]].map do |file|
         require file

data/lib/rom/setup/auto_registration_strategies/base.rb

@@ -3,14 +3,19 @@ require 'rom/initializer'
 
 module ROM
   module AutoRegistrationStrategies
+    # Base class for registration strategies
+    #
+    # @api private
     class Base
       extend Initializer
 
       PathnameType = Types.Definition(Pathname).constrained(type: Pathname)
 
-      option :file, type: Types::Strict::String
-
       EXTENSION_REGEX = /\.rb\z/
+
+      # @!attribute [r] file
+      #   @return [String] Name of a component file
+      option :file, type: Types::Strict::String
     end
   end
 end

data/lib/rom/setup/auto_registration_strategies/custom_namespace.rb

@@ -6,10 +6,22 @@ require 'rom/setup/auto_registration_strategies/base'
 
 module ROM
   module AutoRegistrationStrategies
+    # Custom namespace strategy loads components and assumes they are defined
+    # within the provided namespace
+    #
+    # @api private
     class CustomNamespace < Base
+      # @!attribute [r] directory
+      #   @return [Pathname] The path to dir with components
       option :directory, type: PathnameType
+
+      # @!attribute [r] namespace
+      #   @return [String] Name of a namespace
       option :namespace, type: Types::Strict::String
 
+      # Loads components
+      #
+      # @api private
       def call
         potential = []
         attempted = []
@@ -37,24 +49,29 @@ module ROM
 
       private
 
+      # @api private
       def name_error_message(attempted)
         "required file does not define expected constant name; either " \
         "register your constant explicitly of try following the path" \
         "naming convention like:\n\n\t- #{attempted.join("\n\t- ")}\n"
       end
 
+      # @api private
       def filename
         Pathname(file).basename('.rb')
       end
 
+      # @api private
       def ns_const
         @namespace_constant ||= Dry::Core::Inflector.constantize(namespace)
       end
 
+      # @api private
       def path_arr
         file_path << filename
       end
 
+      # @api private
       def file_path
         File.dirname(file).split("/") - directory.to_s.split("/")
       end