lib/yaks/config/dsl.rb in yaks-0.4.4 vs lib/yaks/config/dsl.rb in yaks-0.5.0

@@ -4,73 +4,160 @@
       # @!attribute [r] config
       #   @return [Yaks::Config]
       attr_reader :config
 
       # @param [Yaks::Config] config
-      # @param [Proc] blk
-      # @return [Yaks::Config::DSL]
-      def initialize(config, &blk)
+      # @param [Proc] block
+      def initialize(config, &block)
         @config       = config
         @policy_class = Class.new(DefaultPolicy)
         @policies     = []
-        instance_eval(&blk) if blk
-        @policies.each do |policy_blk|
-          @policy_class.class_eval &policy_blk
+        instance_eval(&block) if block
+        @policies.each do |policy_block|
+          @policy_class.class_eval &policy_block
         end
         config.policy_class = @policy_class
       end
 
+      # Set the options for a format
+      #
       # @param [Symbol] format
-      # @return [Symbol]
+      # @param [Hash] options
+      #
+      # @example
+      #
+      #   yaks = Yaks.new do
+      #     format_options :hal, {plural_links: [:related_content]}
+      #   end
+      #
       def format_options(format, options)
         config.format_options[format] = options
       end
 
+      # Set the default format
+      #
+      # Defaults to +:hal+
+      #
       # @param [Symbol] format
-      # @return [Symbol]
+      #   Format identifier, one of +Yaks::Format.names+
+      #
+      # @example
+      #
+      #    yaks = Yaks.new do
+      #      default_fomat :json_api
+      #    end
+      #
       def default_format(format)
         config.default_format = format
       end
 
-      # @param [Object] klass
-      # @return [Object]
+      # Configure JSON serializer
+      #
+      # Defaults to JSON.pretty_generate
+      #
+      # @example
+      #
+      #   yaks = Yaks.new do
+      #     json_serializer &Oj.method(:dump)
+      #   end
+      #
+      # @param [Proc] block
+      #   Serialization procedure
+      #
+      def json_serializer(&block)
+        config.serializers[:json] = block
+      end
+
+      %w[before after around skip].map(&:intern).each do |hook_type|
+        define_method hook_type do |step, name = :"#{hook_type}_#{step}", &block|
+          config.hooks << [hook_type, step, name, block]
+        end
+      end
+
+      # Set a different policy implementation
+      #
+      # By default Yaks uses +Yaks::DefaultPolicy+ to derive missing
+      # information. You can swap in a class with a compatible
+      # interface to change the default behavior
+      #
+      # To override a single policy method, simply call a method with
+      # the same name as part of your Yaks configuration, passing a
+      # block to define the new behavior.
+      #
+      # @example
+      #
+      #    yaks = Yaks.new do
+      #      derive_type_from_mapper_class do |mapper_class|
+      #        mapper_class.name.sub(/Mapper^/,'')
+      #      end
+      #    end
+      #
+      # @param [Class] klass
+      #   Policy class
+      #
       def policy(klass)
         @policy_class = klass
       end
 
-      # @param [String] templ
-      # @return [String]
-      def rel_template(templ)
-        config.policy_options[:rel_template] = templ
+      # Set the template for deriving rels
+      #
+      # Used to derive rels for links and subresources.
+      #
+      # @example
+      #
+      #   yaks = Yaks.new do
+      #     rel_template 'http://api.example.com/rels/{rel}'
+      #   end
+      #
+      # @param [String] template
+      #   A valid URI template containing +{rel}+
+      #
+      def rel_template(template)
+        config.policy_options[:rel_template] = template
       end
 
-      # @param [Object] namespace
-      # @return [Object]
+      # Set the namespace (Ruby module) that contains your mappers
+      #
+      # When your mappers don't live at the top-level, then set this
+      # so Yaks can correctly infer the mapper class from the model
+      # class.
+      #
+      # @example
+      #
+      #   yaks = Yaks.new do
+      #     mapper_namespace API::Mappers
+      #   end
+      #
+      #   module API::Mappers
+      #     class FruitMapper < Yaks::Mapper
+      #        ...
+      #     end
+      #   end
+      #
+      #   class Fruit < BaseModel
+      #     ...
+      #   end
+      #
+      # @param [Module] namespace
+      #
       def mapper_namespace(namespace)
         config.policy_options[:namespace] = namespace
       end
       alias namespace mapper_namespace
 
       # @param [Array] args
-      # @param [Proc] blk
-      # @return [Array]
-      def map_to_primitive(*args, &blk)
-        config.primitivize.map(*args, &blk)
-      end
-
       # @param [Proc] block
-      # @return [Array]
-      def after(&block)
-        config.steps << block
+      def map_to_primitive(*args, &block)
+        config.primitivize.map(*args, &block)
       end
 
       # Will define each method available in the DefaultPolicy upon the DSL
       # and then make it available to apply to any Class taking on the
       # `@policies` Array.
       DefaultPolicy.public_instance_methods(false).each do |method|
-        define_method method do |&blk|
+        define_method method do |&block|
           @policies << proc {
-            define_method method, &blk
+            define_method method, &block
           }
         end
       end
     end
   end