lib/dry/schema/macros/dsl.rb in dry-schema-0.6.0 vs lib/dry/schema/macros/dsl.rb in dry-schema-1.0.0

@@ -14,78 +14,149 @@
         include Dry::Logic::Operators
 
         undef :eql?
         undef :nil?
 
-        # @api private
+        # @!attribute [r] chain
+        #   Indicate if the macro should append its rules to the provided trace
+        #   @return [Boolean]
+        #   @api private
         option :chain, default: -> { true }
 
         # @!attribute [r] predicate_inferrer
+        #   PredicateInferrer is used to infer predicate type-check from a type spec
         #   @return [PredicateInferrer]
         #   @api private
         option :predicate_inferrer, default: proc { PredicateInferrer.new(compiler.predicates) }
 
-        # Specify predicates that should be applied to a value
+        # @overload value(*predicates, **predicate_opts)
+        #   Set predicates without and with arguments
         #
+        #   @param [Array<Symbol>] predicates
+        #   @param [Hash] predicate_opts
+        #
+        #   @example with a predicate
+        #     required(:name).value(:filled?)
+        #
+        #   @example with a predicate with arguments
+        #     required(:name).value(min_size?: 2)
+        #
+        #   @example with a predicate with and without arguments
+        #     required(:name).value(:filled?, min_size?: 2)
+        #
+        #   @example with a block
+        #     required(:name).value { filled? & min_size?(2) }
+        #
+        # @return [Macros::Core]
+        #
         # @api public
         def value(*predicates, **opts, &block)
           append_macro(Macros::Value) do |macro|
             macro.call(*predicates, **opts, &block)
           end
         end
 
         # Prepends `:filled?` predicate
         #
+        # @example with a type spec
+        #   required(:name).filled(:string)
+        #
+        # @example with a type spec and a predicate
+        #   required(:name).filled(:string, format?: /\w+/)
+        #
+        # @return [Macros::Core]
+        #
         # @api public
         def filled(*args, &block)
           append_macro(Macros::Filled) do |macro|
             macro.call(*args, &block)
           end
         end
 
-        # Specify a nested hash without enforced hash? type-check
+        # Specify a nested hash without enforced `hash?` type-check
         #
+        # This is a simpler building block than `hash` macro, use it
+        # when you want to provide `hash?` type-check with other rules
+        # manually.
+        #
+        # @example
+        #   required(:tags).value(:hash, min_size?: 1).schema do
+        #     required(:name).value(:string)
+        #   end
+        #
+        # @return [Macros::Core]
+        #
         # @api public
         def schema(*args, &block)
           append_macro(Macros::Schema) do |macro|
             macro.call(*args, &block)
           end
         end
 
-        # Specify a nested hash with enforced hash? type-check
+        # Specify a nested hash with enforced `hash?` type-check
         #
-        # @see #schema
+        # @example
+        #   required(:tags).hash do
+        #     required(:name).value(:string)
+        #   end
         #
         # @api public
         def hash(*args, &block)
           append_macro(Macros::Hash) do |macro|
             macro.call(*args, &block)
           end
         end
 
         # Specify predicates that should be applied to each element of an array
         #
+        # This is a simpler building block than `array` macro, use it
+        # when you want to provide `array?` type-check with other rules
+        # manually.
+        #
+        # @example a list of strings
+        #   required(:tags).value(:array, min_size?: 2).each(:str?)
+        #
+        # @example a list of hashes
+        #   required(:tags).value(:array, min_size?: 2).each(:hash) do
+        #     required(:name).filled(:string)
+        #   end
+        #
+        # @return [Macros::Core]
+        #
         # @api public
         def each(*args, &block)
           append_macro(Macros::Each) do |macro|
             macro.value(*args, &block)
           end
         end
 
-        # Like `each`, but prepends `array?` check
+        # Like `each` but sets `array?` type-check
         #
+        # @example a list of strings
+        #   required(:tags).array(:str?)
+        #
+        # @example a list of hashes
+        #   required(:tags).array(:hash) do
+        #     required(:name).filled(:string)
+        #   end
+        #
+        # @return [Macros::Core]
+        #
         # @api public
         def array(*args, &block)
           append_macro(Macros::Array) do |macro|
             macro.value(*args, &block)
           end
         end
 
         # Set type spec
         #
-        # @param [Symbol, Array, Dry::Types::Type]
+        # @example
+        #   required(:name).type(:string).value(min_size?: 2)
         #
+        # @param [Symbol, Array, Dry::Types::Type] spec
+        #
         # @return [Macros::Key]
         #
         # @api public
         def type(spec)
           schema_dsl.set_type(name, spec)
@@ -127,16 +198,18 @@
 
             type(resolved_type) if set_type
 
             type_predicates = predicate_inferrer[resolved_type]
 
-            unless predicates.include?(type_predicates)
+            unless type_predicates.empty? || predicates.include?(type_predicates)
               if type_predicates.is_a?(::Array) && type_predicates.size.equal?(1)
                 predicates.unshift(type_predicates[0])
               else
                 predicates.unshift(type_predicates)
               end
             end
+
+            return self if predicates.empty?
           end
 
           yield(*predicates, type_spec: type_spec)
         end
       end