Merge pull request rails#43089 from kaukas/template-gem-comments

Support gem comments in Rails templates

Author: guilleiguaran

railties/CHANGELOG.md

@@ -137,5 +137,9 @@
 
     *Gannon McGibbon*
 
+*   Add support for comments above gem declaration in Rails application templates, e.g. `gem("nokogiri", comment: "For XML")`.
+
+    *Linas Juškevičius*
+
 
 Please check [6-1-stable](https://github.com/rails/rails/blob/6-1-stable/railties/CHANGELOG.md) for previous changes.

railties/lib/rails/generators/actions.rb

@@ -18,6 +18,7 @@ def initialize(*) # :nodoc:
       #   gem "technoweenie-restful-authentication", lib: "restful-authentication", source: "http://gems.github.com/"
       #   gem "rails", "3.0", git: "https://github.com/rails/rails"
       #   gem "RedCloth", ">= 4.1.0", "< 4.2.0"
+      #   gem "rspec", comment: "Put this comment above the gem declaration"
       def gem(*args)
         options = args.extract_options!
         name, *versions = args
@@ -26,6 +27,9 @@ def gem(*args)
         # otherwise use name (version).
         parts, message = [ quote(name) ], name.dup
 
+        # Output a comment above the gem declaration.
+        comment = options.delete(:comment)
+
         if versions = versions.any? ? versions : options.delete(:version)
           _versions = Array(versions)
           _versions.each do |version|
@@ -40,9 +44,17 @@ def gem(*args)
         parts << quote(options) unless options.empty?
 
         in_root do
-          str = "gem #{parts.join(", ")}"
-          str = indentation + str
-          append_file_with_newline "Gemfile", str, verbose: false
+          str = []
+          if comment
+            comment.each_line do |comment_line|
+              str << indentation
+              str << "# #{comment_line}"
+            end
+            str << "\n"
+          end
+          str << indentation
+          str << "gem #{parts.join(", ")}"
+          append_file_with_newline "Gemfile", str.join, verbose: false
         end
       end
 

railties/test/generators/actions_test.rb

@@ -116,6 +116,22 @@ def test_gem_should_include_options
     assert_file "Gemfile", /gem "rspec", github: "dchelimsky\/rspec", tag: "1\.2\.9\.rc1"/
   end
 
+  def test_gem_should_put_the_comment_before_gem_declaration
+    run_generator
+
+    action :gem, "rspec", comment: "Use RSpec"
+
+    assert_file "Gemfile", /# Use RSpec\ngem "rspec"/
+  end
+
+  def test_gem_should_support_multiline_comments
+    run_generator
+
+    action :gem, "rspec", comment: "Use RSpec\nReplaces minitest"
+
+    assert_file "Gemfile", /# Use RSpec\n# Replaces minitest\ngem "rspec"/
+  end
+
   def test_gem_with_non_string_options
     run_generator
 
@@ -156,6 +172,26 @@ def test_gem_group_should_wrap_gems_in_a_group
     assert_file "Gemfile", /\n\ngroup :development, :test do\n  gem "rspec-rails"\nend\n\ngroup :test do\n  gem "fakeweb"\nend\n\z/
   end
 
+  def test_gem_group_should_indent_comments
+    run_generator
+
+    action :gem_group, :test do
+      gem "fakeweb", comment: "Fake requests"
+    end
+
+    assert_file "Gemfile", /\n\ngroup :test do\n  # Fake requests\n  gem "fakeweb"\nend\n\z/
+  end
+
+  def test_gem_group_should_indent_multiline_comments
+    run_generator
+
+    action :gem_group, :test do
+      gem "fakeweb", comment: "Fake requests\nNeeded in tests"
+    end
+
+    assert_file "Gemfile", /\n\ngroup :test do\n  # Fake requests\n  # Needed in tests\n  gem "fakeweb"\nend\n\z/
+  end
+
   def test_github_should_create_an_indented_block
     run_generator