wallaby 5.1.5 → 5.1.6

data/lib/decorators/wallaby/abstract_resource_decorator.rb

@@ -5,15 +5,15 @@ module Wallaby
       # Guess the model class from class name
       # @return [Class]
       def model_class
-        return unless self < ::Wallaby::ResourceDecorator
-        Map.model_class_map name.gsub 'Decorator', EMPTY_STRING
+        return unless self < ::Wallaby.configuration.mapping.resource_decorator
+        Map.model_class_map name.gsub('Decorator', EMPTY_STRING)
       end
 
       # Get the model decorator for the model class
       # It should be the same as #model_decorator
-      # @return Wallaby::ModelDecorator
+      # @return [Wallaby::ModelDecorator]
       def model_decorator
-        return unless self < ::Wallaby::ResourceDecorator
+        return unless self < ::Wallaby.configuration.mapping.resource_decorator
         Map.model_decorator_map model_class
       end
 
@@ -25,6 +25,7 @@ module Wallaby
 
     attr_reader :resource, :model_decorator
 
+    # @param resource [Object] resource object
     def initialize(resource)
       @resource = resource
       @model_decorator = Map.model_decorator_map model_class
@@ -62,11 +63,15 @@ module Wallaby
     delegate :to_s, :to_param, to: :resource
 
     # We delegate missing methods to resource
+    # @param method_id [String,Symbol]
+    # @param args [Array]
     def method_missing(method_id, *args)
       return super unless @resource.respond_to? method_id
       @resource.public_send method_id, *args
     end
 
+    # @param method_id [String,Symbol]
+    # @param _include_private [Boolean]
     def respond_to_missing?(method_id, _include_private)
       @resource.respond_to?(method_id) || super
     end

data/lib/errors/wallaby/model_not_found.rb

@@ -1,6 +1,7 @@
 module Wallaby
   # Model not found error
   class ModelNotFound < NotFound
+    # @return [String] not found error message
     def message
       I18n.t 'errors.not_found.model', model: super
     end

data/lib/errors/wallaby/resource_not_found.rb

@@ -1,6 +1,7 @@
 module Wallaby
   # Resource not found error
   class ResourceNotFound < NotFound
+    # @return [String] resource not found error message
     def message
       I18n.t 'errors.not_found.resource', resource: super
     end

data/lib/forms/wallaby/form_builder.rb

@@ -23,14 +23,16 @@ module Wallaby
     end
 
     # Extend label to accept proc type `text` argument
+    # @see ActionView::Helpers::FormBuilder#label
     def label(method, text = nil, options = {}, &block)
-      text = instance_exec(&text) if text.respond_to? :call
+      text = instance_exec(&text) if text.is_a?(Proc)
       super
     end
 
     # Extend select to accept proc type `choices` argument
+    # @see ActionView::Helpers::FormBuilder#select
     def select(method, choices = nil, options = {}, html_options = {}, &block)
-      choices = instance_exec(&choices) if choices.respond_to? :call
+      choices = instance_exec(&choices) if choices.is_a?(Proc)
       super
     end
 
@@ -40,7 +42,7 @@ module Wallaby
     def method_missing(method, *args, &block)
       return super unless @template.respond_to? method
       # Delegate the method so that we don't come in here the next time
-      # same method is called
+      # when same method is called
       self.class.delegate method, to: :@template
       @template.public_send method, *args, &block
     end

data/lib/helpers/wallaby/application_helper.rb

@@ -2,7 +2,10 @@ module Wallaby
   # Application helper
   module ApplicationHelper
     # Override `actionview/lib/action_view/routing_url_for.rb#url_for`
-    # to handle the url_for properly for wallaby engine
+    # to handle the url_for properly for wallaby engine when options contains
+    # values of both `:resources` and `:action`
+    # @param options [String, Hash]
+    # @return [String] url
     def url_for(options = nil)
       # possible Hash or Parameters
       if options.respond_to?(:to_h) \
@@ -14,6 +17,9 @@ module Wallaby
     end
 
     # Add turbolinks options when it's enabled
+    # @see ActionView::Helpers::AssetTagHelper#stylesheet_link_tag
+    # @param sources [Array<String>] source name under `app/assets/stylesheets`
+    # @return [String] a list of stylesheet link tags
     def stylesheet_link_tag(*sources)
       default_options =
         if Wallaby.configuration.features.turbolinks_enabled
@@ -26,6 +32,9 @@ module Wallaby
     end
 
     # Add turbolinks options when it's enabled
+    # @see ActionView::Helpers::AssetTagHelper#javascript_include_tag
+    # @param sources [Array<String>] source name under `app/assets/javascripts`
+    # @return [String] a list of javascript script tags
     def javascript_include_tag(*sources)
       default_options =
         if Wallaby.configuration.features.turbolinks_enabled

data/lib/helpers/wallaby/base_helper.rb

@@ -5,15 +5,21 @@ module Wallaby
     include LinksHelper
 
     # @see Utils.to_model_label
+    # @return [String] label for given model class
     def to_model_label(model_class)
       Utils.to_model_label model_class
     end
 
     # @see Map.resources_name_map
+    # @return [String] resources name for given model class
     def to_resources_name(model_class)
       Map.resources_name_map model_class
     end
 
+    # Generate body class from the following sources:
+    # - `:action` parameter
+    # - converted current resources name (e.g. `order__item` from `Order::Item`)
+    # - `:custom_body_class` content
     # @return [String] css classes for body tag
     def body_class
       [
@@ -23,9 +29,10 @@ module Wallaby
       ].compact.join SPACE
     end
 
-    # Turn a list of classes into tree structure
-    # @param classes [Array] a list of all the classes that wallaby supports
-    # @return [Array] a tree structure of given classes
+    # Turn a list of classes into tree structure by inheritance.
+    # @param classes [Array<Class>]
+    #   a list of all the classes that wallaby supports
+    # @return [Array<Wallaby::Node>] a tree structure of given classes
     def model_classes(classes = Map.model_classes)
       nested_hash = classes.each_with_object({}) do |klass, hash|
         hash[klass] = Node.new(klass)
@@ -37,7 +44,8 @@ module Wallaby
       nested_hash.values.select { |v| v.parent.nil? }
     end
 
-    # @param array [Array] root classes
+    # Turn the tree of classes into a nested `ul` list.
+    # @param array [Array<Wallaby::Node>] root classes
     # @return [String] HTML for the whole tree
     def model_tree(array)
       return EMPTY_STRING.html_safe if array.blank?

data/lib/helpers/wallaby/form_helper.rb

@@ -3,17 +3,19 @@ module Wallaby
   module FormHelper
     # @param options [Hash, String]
     # @param locals [Hash] local variables for the partial
+    # @return [String] rendered type partial for a form
     def form_type_partial_render(options = {}, locals = {}, &block)
       PartialRenderer.render_form self, options, locals, &block
     end
 
     # To generate remote url for auto select plugin.
-    # @see app/assets/javascripts/wallaby/auto_select.js
+    # @see https://github.com/reinteractive/wallaby/blob/master/app/assets/javascripts/wallaby/auto_select.js
     # @param url [String, nil]
     #   if url is nil, it will fall back to default remote url
     # @param model_class [Class]
     # @param wildcard [String] wildcard that auto_select uses to replace with
     #   the typed keyword
+    # @return [String] url for autocomplete
     def remote_url(url, model_class, wildcard = 'QUERY')
       url ||
         index_path(
@@ -24,13 +26,14 @@ module Wallaby
     end
 
     # To generate dropdown options (class => url) for polymorphic class.
-    # @see app/assets/javascripts/wallaby/auto_select.js
+    # @see https://github.com/reinteractive/wallaby/blob/master/app/assets/javascripts/wallaby/auto_select.js
     # This function will pull out remote urls from `metadata[:remote_urls]`
     # (Class => url).
+    # @see ActionView::Helpers::FormOptionsHelper#options_for_select
     # @param metadata [Hash]
-    # @param wildcard [String]
+    # @param wildcard [String] wildcard to be used in the url
     # @param select_options [Hash]
-    # @return [String] HTML
+    # @return [String] options HTML
     def polymorphic_options(metadata, wildcard = 'QUERY', select_options = {})
       urls = metadata[:remote_urls] || {}
       options = (metadata[:polymorphic_list] || []).map do |klass|

data/lib/helpers/wallaby/links_helper.rb

@@ -1,16 +1,17 @@
 module Wallaby
   # Links helper
   module LinksHelper
-    # Permit the params used by Wallaby
+    # @return [ActionController::Parameters] whitelisted params used by Wallaby
     def index_params
       params.except(:resources, :utf8).permit(:filter, :page, :per, :q, :sort)
     end
 
     # Return link to index page by a given model class
+    #
     # If user's not authorized, nil will be returned
     # @param model_class [Class] model class
     # @param url_params [ActionController::Parameters, Hash]
-    # @param html_options [Hash] (see ActionView::Helpers::UrlHelper#link_to)
+    # @param html_options [Hash] (@see ActionView::Helpers::UrlHelper#link_to)
     # @return [String, nil] anchor element
     def index_link(model_class, url_params: {}, html_options: {}, &block)
       return if cannot? :index, model_class
@@ -24,10 +25,11 @@ module Wallaby
     end
 
     # Return link to create page by a given model class
+    #
     # If user's not authorized, nil will be returned
     # @param model_class [Class] model class
     # @param options [Hash]
-    # @param html_options [Hash] (see ActionView::Helpers::UrlHelper#link_to)
+    # @param html_options [Hash] (@see ActionView::Helpers::UrlHelper#link_to)
     # @return [String, nil] anchor element
     def new_link(model_class, html_options: {}, &block)
       return if cannot? :new, model_class
@@ -44,7 +46,7 @@ module Wallaby
     # If user's not authorized, resource label will be returned
     # @param resource [Object, Wallaby::ResourceDecorator] model class
     # @param options [Hash]
-    # @param html_options [Hash] (see ActionView::Helpers::UrlHelper#link_to)
+    # @param html_options [Hash] (@see ActionView::Helpers::UrlHelper#link_to)
     # @return [String] anchor element / text
     def show_link(resource, options: {}, html_options: {}, &block)
       # NOTE: to_s is a must
@@ -64,7 +66,7 @@ module Wallaby
     # If user's not authorized, resource label will be returned
     # @param resource [Object, Wallaby::ResourceDecorator] model class
     # @param options [Hash]
-    # @param html_options [Hash] (see ActionView::Helpers::UrlHelper#link_to)
+    # @param html_options [Hash] (@see ActionView::Helpers::UrlHelper#link_to)
     # @return [String] anchor element / text
     def edit_link(resource, options: {}, html_options: {}, &block)
       default = options[:readonly] && decorate(resource).to_label || nil
@@ -80,10 +82,11 @@ module Wallaby
     end
 
     # Return link to delete action by a given model class
+    #
     # If user's not authorized, nil will be returned
     # @param resource [Object, Wallaby::ResourceDecorator] model class
     # @param options [Hash]
-    # @param html_options [Hash] (see ActionView::Helpers::UrlHelper#link_to)
+    # @param html_options [Hash] (@see ActionView::Helpers::UrlHelper#link_to)
     # @return [String, nil] anchor element
     def delete_link(resource, html_options: {}, &block)
       return if cannot? :destroy, extract(resource)
@@ -102,7 +105,7 @@ module Wallaby
     end
 
     # Return link to cancel an action
-    # @param html_options [Hash] (see ActionView::Helpers::UrlHelper#link_to)
+    # @param html_options [Hash] (@see ActionView::Helpers::UrlHelper#link_to)
     # @return [String] HTML anchor element
     def cancel_link(html_options = {}, &block)
       block ||= -> { t 'links.cancel' }

data/lib/helpers/wallaby/resources_helper.rb

@@ -4,6 +4,8 @@ module Wallaby
     include FormHelper
     include IndexHelper
 
+    # @see Map.model_decorator_map
+    # @return [Wallaby::ModelDecorator]
     def model_decorator(model_class)
       Map.model_decorator_map model_class
     end

data/lib/helpers/wallaby/secure_helper.rb

@@ -1,7 +1,9 @@
 module Wallaby
   # Secure helper
   module SecureHelper
-    # Image portrait for given user
+    # Image portrait for given user.
+    # - if email is present, a gravatar image tag will be returned
+    # - otherwise, an user icon will be returned
     # @param user [Object]
     # @return [String] IMG or I element
     def user_portrait(user = current_user)
@@ -18,20 +20,24 @@ module Wallaby
     end
 
     # Logout path for given user
+    # @see Wallaby::Configuration::Security#logout_path
     # @param user [Object]
     # @param app [Object]
-    # @return [String] HTML anchor element
+    # @return [String] url to log out
     def logout_path(user = current_user, app = main_app)
       path = Wallaby.configuration.security.logout_path
-      path ||= if defined? ::Devise
-                 scope = ::Devise::Mapping.find_scope! user
-                 "destroy_#{scope}_session_path"
-               end
+      path ||=
+        if defined? ::Devise
+          scope = ::Devise::Mapping.find_scope! user
+          "destroy_#{scope}_session_path"
+        end
       app.public_send path if path && app.respond_to?(path)
     end
 
     # Logout method for given user
-    # @return [String, Symbol]
+    # @see Wallaby::Configuration::Security#logout_method
+    # @param user [Object]
+    # @return [String, Symbol] http method to log out
     def logout_method(user = current_user)
       http_method = Wallaby.configuration.security.logout_method
       http_method || if defined? ::Devise

data/lib/helpers/wallaby/styling_helper.rb

@@ -2,7 +2,7 @@ module Wallaby
   # Styling helper
   module StylingHelper
     # Shortcut to build up the html options as keyword arguments
-    # @param string_or_array [String, Array]
+    # @param string_or_array [String, Array<String>]
     # @return [Hash]
     def html_classes(string_or_array)
       { html_options: { class: string_or_array } }

data/lib/interfaces/wallaby/mode.rb

@@ -1,24 +1,46 @@
 module Wallaby
   # This is the abstract class that all ORM modes to have implemented.
   class Mode
-    INTERFACE_METHODS = %w(
-      model_decorator model_finder
-      model_service_provider model_pagination_provider
-    ).freeze
+    class << self
+      # @see Wallaby::ModelDecorator
+      # @return [Wallaby::ModelDecorator] model decorator for the mode
+      def model_decorator
+        check_and_constantize __callee__
+      end
+
+      # @see Wallaby::ModelFinder
+      # @return [Wallaby::ModelFinder] model finder for the mode
+      def model_finder
+        check_and_constantize __callee__
+      end
+
+      # @see Wallaby::ModelServiceProvider
+      # @return [Wallaby::ModelServiceProvider] service provider for the mode
+      def model_service_provider
+        check_and_constantize __callee__
+      end
+
+      # @see Wallaby::ModelPaginationProvider
+      # @return [Wallaby::ModelPaginationProvider]
+      # pagination provider for the mode
+      def model_pagination_provider
+        check_and_constantize __callee__
+      end
+
+      private
 
-    INTERFACE_METHODS.each do |method_id|
-      define_singleton_method method_id do
-        begin
-          method_class  = __callee__.to_s.classify
-          class_name    = "#{name}::#{method_class}"
-          parent_class  = "Wallaby::#{method_class}".constantize
-          class_name.constantize.tap do |klass|
-            next if klass < parent_class
-            raise InvalidError, "#{klass} must inherit #{parent_class}"
-          end
-        rescue NameError
-          raise NotImplemented, class_name
+      #
+      # @return [Class] constantized class
+      def check_and_constantize(method_id)
+        method_class  = method_id.to_s.classify
+        class_name    = "#{name}::#{method_class}"
+        parent_class  = "Wallaby::#{method_class}".constantize
+        class_name.constantize.tap do |klass|
+          next if klass < parent_class
+          raise InvalidError, "#{klass} must inherit #{parent_class}"
         end
+      rescue NameError
+        raise NotImplemented, class_name
       end
     end
   end

data/lib/interfaces/wallaby/model_decorator.rb

@@ -1,8 +1,8 @@
 module Wallaby
-  # Model Decorator interface, designed to maintain metadata information for all
+  # Model Decorator interface, designed to maintain metadata for all
   # the fields coming from data source (database/api)
   # @see Wallaby::ResourceDecorator for more information on how to customize
-  #   metadata information
+  #   metadata
   class ModelDecorator
     include FieldHelpers
 
@@ -10,83 +10,85 @@ module Wallaby
     attr_writer \
       :field_names, :index_field_names, :show_field_names, :form_field_names
 
+    # Initialize with model class
+    # @param model_class [Class] model class
     def initialize(model_class)
       @model_class = model_class
     end
 
-    # @return [Hash] metadata information for all fields that index/show/form
-    #   will copy
+    # @return [Hash] origin metadata for fields
     def fields
       raise NotImplemented
     end
 
-    # @param fields [Hash] metadata information for all fields
+    # Set metadata as origin
+    # @param fields [Hash] metadata
     def fields=(fields)
       @fields = ::ActiveSupport::HashWithIndifferentAccess.new fields
     end
 
-    # @return [Array] field names
+    # @return [Array<String>, Array<Symbol>] a list of field names
     def field_names
       @field_names ||= reposition fields.keys, primary_key
     end
 
-    # @return [Hash] metadata information for all fields that would be used on
-    #   index page
+    # @return [Hash] metadata for fields used on index page
     def index_fields
       raise NotImplemented
     end
 
-    # @param fields [Hash] metadata information for all fields that would be
-    #   used on index page
+    # Set metadata for index page
+    # @param fields [Hash] metadata
     def index_fields=(fields)
       @index_fields = ::ActiveSupport::HashWithIndifferentAccess.new fields
     end
 
-    # @return [Array] field names of index page
+    # @return [Array<String>, Array<Symbol>]
+    #   a list of field names displayed on index page
     def index_field_names
       @index_field_names ||= reposition index_fields.keys, primary_key
     end
 
-    # @return [Hash] metadata information for all fields that would be used on
-    #   show page
+    # @return [Hash] metadata for fields used on show page
     def show_fields
       raise NotImplemented
     end
 
-    # @param fields [Hash] metadata information for all fields that would be
-    #   used on show page
+    # Set metadata for show page
+    # @param fields [Hash] metadata
     def show_fields=(fields)
       @show_fields = ::ActiveSupport::HashWithIndifferentAccess.new fields
     end
 
-    # @return [Array] field names of show page
+    # @return [Array<String>, Array<Symbol>]
+    #   a list of field names displayed on show page
     def show_field_names
       @show_field_names ||= reposition show_fields.keys, primary_key
     end
 
-    # @return [Hash] metadata information for all fields that would be used on
-    #   form page
+    # @return [Hash] metadata for fields used on form (new/edit) page
     def form_fields
       raise NotImplemented
     end
 
-    # @param fields [Hash] metadata information for all fields that would be
-    #   used on form page
+    # Set metadata for form (new/edit) page
+    # @param fields [Hash] metadata
     def form_fields=(fields)
       @form_fields = ::ActiveSupport::HashWithIndifferentAccess.new fields
     end
 
-    # @return [Array] field names of form page
+    # @return [Array<String>, Array<Symbol>]
+    #   a list field names displayed on form (new/edit) page
     def form_field_names
       @form_field_names ||= reposition form_fields.keys, primary_key
     end
 
-    # @return [Hash] custom filters
+    # @return [Hash] metadata for custom filters used on index page
     def filters
       @filters ||= ::ActiveSupport::HashWithIndifferentAccess.new
     end
 
-    # @return [Hash] errors
+    # @return [Hash] validation errors for current resource
     def form_active_errors(_resource)
       raise NotImplemented
     end
@@ -96,22 +98,29 @@ module Wallaby
       raise NotImplemented
     end
 
+    # To guess the title for a resource.
+    #
+    # This title will be used on the following places:
+    # - page title on show page
+    # - in the response for autocomplete association field
+    # - title of show link for a resource
     # @param _resource [Object] resource
-    # @return [String] title of given resource
+    # @return [String] title of current resource
     def guess_title(_resource)
       raise NotImplemented
     end
 
-    # @return [String] resources name mapped from model class
+    # @return [String] resources name coverted from model class
     def resources_name
       Map.resources_name_map @model_class
     end
 
     protected
 
-    # @param field_names [Array] field names
+    # @param field_names [Array<String>, Array<Symbol>] field names
     # @param primary_key [String] primary key name
-    # @return [Array] a list of field names that primary key goes first
+    # @return [Array<String>, Array<Symbol>]
+    #   a list of field names that primary key goes first
     def reposition(field_names, primary_key)
       field_names.unshift(primary_key).uniq
     end