Merge pull request #1649 from bf4/rails_template_update

[DOC] Improvements from Rails plugin template

Author: bf4

Gemfile

@@ -50,4 +50,5 @@ end
 
 group :development, :test do
   gem 'rubocop', '~> 0.36', require: false
+  gem 'yard', require: false
 end

LICENSE.txt renamed to MIT-LICENSE

@@ -1,11 +1,34 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
 begin
   require 'simplecov'
 rescue LoadError
 end
 
-require 'bundler'
-Bundler.setup
-require 'bundler/gem_tasks'
+Bundler::GemHelper.install_tasks
+
+require 'yard'
+
+namespace :yard do
+  YARD::Rake::YardocTask.new(:doc) do |t|
+    t.stats_options = ['--list-undoc']
+  end
+
+  desc 'start a gem server'
+  task :server do
+    sh 'bundle exec yard server --gems'
+  end
+
+  desc 'use Graphviz to generate dot graph'
+  task :graph do
+    output_file = 'doc/erd.dot'
+    sh "bundle exec yard graph --protected --full --dependencies > #{output_file}"
+    puts 'open doc/erd.dot if you have graphviz installed'
+  end
+end
 
 begin
   require 'rubocop'
@@ -31,18 +54,18 @@ else
     Rake::Task[:rubocop].clear if Rake::Task.task_defined?(:rubocop)
     desc 'Execute rubocop'
     RuboCop::RakeTask.new(:rubocop) do |task|
-      task.options = ['--display-cop-names', '--display-style-guide']
+      task.options = ['--rails', '--display-cop-names', '--display-style-guide']
       task.fail_on_error = true
     end
   end
 end
 
 require 'rake/testtask'
 
-Rake::TestTask.new do |t|
-  t.libs << 'test'
+Rake::TestTask.new(:test) do |t|
   t.libs << 'lib'
-  t.test_files = FileList['test/**/*_test.rb']
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
   t.ruby_opts = ['-r./test/test_helper.rb']
   t.ruby_opts << ' -w' unless ENV['NO_WARN'] == 'true'
   t.verbose = true

Rakefile

@@ -2,16 +2,15 @@ module ActiveModel
   class Serializer
     # This class hold all information about serializer's association.
     #
-    # @param [Symbol] name
-    # @param [ActiveModel::Serializer] serializer
-    # @param [Hash{Symbol => Object}] options
+    # @attr [Symbol] name
+    # @attr [ActiveModel::Serializer] serializer
+    # @attr [Hash{Symbol => Object}] options
     #
     # @example
     #  Association.new(:comments, CommentSummarySerializer)
     #
     Association = Struct.new(:name, :serializer, :options, :links, :meta) do
       # @return [Symbol]
-      #
       def key
         options.fetch(:key, name)
       end

lib/active_model/serializer/association.rb

@@ -74,7 +74,7 @@ def fragmented(serializer)
         # Sets +::_cache+ object to <tt>ActionController::Base.cache_store</tt>
         #   when Rails.configuration.action_controller.perform_caching
         #
-        # @params options [Hash] with valid keys:
+        # @param options [Hash] with valid keys:
         #   cache_store    : @see ::_cache
         #   key            : @see ::_cache_key
         #   only           : @see ::_cache_only

lib/active_model/serializer/caching.rb

@@ -26,7 +26,7 @@ def adapter_class(adapter)
         ActiveModelSerializers::Adapter.lookup(adapter)
       end
 
-      # @return Hash<adapter_name, adapter_class>
+      # @return [Hash<adapter_name, adapter_class>]
       def adapter_map
         ADAPTER_MAP
       end

lib/active_model_serializers/adapter.rb

@@ -8,8 +8,8 @@ module Error
         # Builds a JSON API Errors Object
         # {http://jsonapi.org/format/#errors JSON API Errors}
         #
-        # @param [ActiveModel::Serializer::ErrorSerializer]
-        # @return [Array<Symbol, Array<String>] i.e. attribute_name, [attribute_errors]
+        # @param [ActiveModel::Serializer::ErrorSerializer] error_serializer
+        # @return [Array<Symbol, Array<String>>] i.e. attribute_name, [attribute_errors]
         def self.resource_errors(error_serializer)
           error_serializer.as_json.flat_map do |attribute_name, attribute_errors|
             attribute_error_objects(attribute_name, attribute_errors)

lib/active_model_serializers/adapter/json_api/error.rb

@@ -52,8 +52,9 @@ def object_cache_key
     end
 
     # find all cache_key for the collection_serializer
-    # @param collection_serializer
-    # @param include_tree
+    # @param serializers [ActiveModel::Serializer::CollectionSerializer]
+    # @param adapter_instance [ActiveModelSerializers::Adapter::Base]
+    # @param include_tree [ActiveModel::Serializer::IncludeTree]
     # @return [Array] all cache_key of collection_serializer
     def self.object_cache_keys(serializers, adapter_instance, include_tree)
       cache_keys = []

lib/active_model_serializers/cached_serializer.rb

@@ -2,8 +2,8 @@ module ActiveModelSerializers
   module Test
     module Schema
       # A Minitest Assertion that test the response is valid against a schema.
-      # @params schema_path [String] a custom schema path
-      # @params message [String] a custom error message
+      # @param schema_path [String] a custom schema path
+      # @param message [String] a custom error message
       # @return [Boolean] true when the response is valid
       # @return [Minitest::Assertion] when the response is invalid
       # @example

lib/active_model_serializers/test/schema.rb

@@ -32,3 +32,14 @@ def assigns(key = nil)
     key.nil? ? assigns : assigns[key]
   end
 end
+
+# ActiveRecord::Migrator.migrations_paths = [File.expand_path("../../test/dummy/db/migrate", __FILE__)]
+# ActiveRecord::Migrator.migrations_paths << File.expand_path('../../db/migrate', __FILE__)
+#
+# Load fixtures from the engine
+# if ActiveSupport::TestCase.respond_to?(:fixture_path=)
+#   ActiveSupport::TestCase.fixture_path = File.expand_path("../fixtures", __FILE__)
+#   ActionDispatch::IntegrationTest.fixture_path = ActiveSupport::TestCase.fixture_path
+#   ActiveSupport::TestCase.file_fixture_path = ActiveSupport::TestCase.fixture_path + "/files"
+#   ActiveSupport::TestCase.fixtures :all
+# end

test/support/rails_app.rb

@@ -1,3 +1,5 @@
+# Configure Rails Environment
+ENV['RAILS_ENV'] = 'test'
 require 'bundler/setup'
 
 begin
@@ -35,10 +37,15 @@
   $minitest_version = 5
   # https://github.com/seattlerb/minitest/blob/e21fdda9d/lib/minitest/autorun.rb
   # https://github.com/seattlerb/minitest/blob/e21fdda9d/lib/minitest.rb#L45-L59
+  # Filter out Minitest backtrace while allowing backtrace from other libraries
+  # to be shown.
+  Minitest.backtrace_filter = Minitest::BacktraceFilter.new
 end
 
 require 'support/rails_app'
 
+# require "rails/test_help"
+
 require 'support/serialization_testing'
 
 require 'support/rails5_shims'