Update generated documentation

Author: jakeonfire

config/contents/bundler/gem_comment.md

@@ -0,0 +1,54 @@
+Add a comment describing each gem in your Gemfile.
+
+Optionally, the "OnlyFor" configuration
+can be used to only register offenses when the gems
+use certain options or have version specifiers.
+Add "version_specifiers" and/or the gem option names
+you want to check.
+
+A useful use-case is to enforce a comment when using
+options that change the source of a gem:
+
+- `bitbucket`
+- `gist`
+- `git`
+- `github`
+- `source`
+
+For a full list of options supported by bundler,
+you can check the https://bundler.io/man/gemfile.5.html[official documentation].
+
+### Example: OnlyFor: [] (default)
+    # bad
+
+    gem 'foo'
+
+    # good
+
+    # Helpers for the foo things.
+    gem 'foo'
+
+### Example: OnlyFor: ['version_specifiers']
+    # bad
+
+    gem 'foo', '< 2.1'
+
+    # good
+
+    # Version 2.1 introduces breaking change baz
+    gem 'foo', '< 2.1'
+
+### Example: OnlyFor: ['version_specifiers', 'github']
+    # bad
+
+    gem 'foo', github: 'some_account/some_fork_of_foo'
+
+    gem 'bar', '< 2.1'
+
+    # good
+
+    # Using this fork because baz
+    gem 'foo', github: 'some_account/some_fork_of_foo'
+
+    # Version 2.1 introduces breaking change baz
+    gem 'bar', '< 2.1'

config/contents/bundler/insecure_protocol_source.md

@@ -1,4 +1,4 @@
-The symbol argument `:gemcutter`, `:rubygems` and `:rubyforge`
+The symbol argument `:gemcutter`, `:rubygems`, and `:rubyforge`
 are deprecated. So please change your source to URL string that
 'https://rubygems.org' if possible, or 'http://rubygems.org' if not.
 
@@ -8,8 +8,8 @@ most use cases HTTPS will be fine.
 
 However, it don't replace all `sources` of `http://` with `https://`.
 For example, when specifying an internal gem server using HTTP on the
-intranet, a use case where HTTPS can not be specified was considered.
-Consider using HTTP only if you can not use HTTPS.
+intranet, a use case where HTTPS cannot be specified was considered.
+Consider using HTTP only if you cannot use HTTPS.
 
 ### Example:
     # bad

config/contents/cop/semantic_blocks.md

@@ -0,0 +1,3 @@
+If there are no parentheses around the arguments, then braces
+and do-end have different meaning due to how they bind, so we
+allow either.

config/contents/gemspec/duplicated_assignment.md

@@ -3,7 +3,7 @@ in a gemspec.
 
 Assigning to an attribute with the same name using `spec.foo =` will be
 an unintended usage. On the other hand, duplication of methods such
-as `spec.requirements`, `spec.add_runtime_dependency` and others are
+as `spec.requirements`, `spec.add_runtime_dependency`, and others are
 permitted because it is the intended use of appending values.
 
 ### Example:

config/contents/gemspec/required_ruby_version.md

@@ -1,32 +1,42 @@
-Checks that `required_ruby_version` of gemspec and `TargetRubyVersion`
-of .rubocop.yml are equal.
+Checks that `required_ruby_version` of gemspec is specified and
+equal to `TargetRubyVersion` of .rubocop.yml.
 Thereby, RuboCop to perform static analysis working on the version
 required by gemspec.
 
 ### Example:
-    # When `TargetRubyVersion` of .rubocop.yml is `2.3`.
+    # When `TargetRubyVersion` of .rubocop.yml is `2.5`.
 
     # bad
     Gem::Specification.new do |spec|
-      spec.required_ruby_version = '>= 2.2.0'
+      # no `required_ruby_version` specified
     end
 
     # bad
     Gem::Specification.new do |spec|
       spec.required_ruby_version = '>= 2.4.0'
     end
 
+    # bad
+    Gem::Specification.new do |spec|
+      spec.required_ruby_version = '>= 2.6.0'
+    end
+
+    # good
+    Gem::Specification.new do |spec|
+      spec.required_ruby_version = '>= 2.5.0'
+    end
+
     # good
     Gem::Specification.new do |spec|
-      spec.required_ruby_version = '>= 2.3.0'
+      spec.required_ruby_version = '>= 2.5'
     end
 
     # good
     Gem::Specification.new do |spec|
-      spec.required_ruby_version = '>= 2.3'
+      spec.required_ruby_version = ['>= 2.5.0', '< 2.7.0']
     end
 
     # good
     Gem::Specification.new do |spec|
-      spec.required_ruby_version = ['>= 2.3.0', '< 2.5.0']
+      spec.required_ruby_version = '~> 2.5'
     end

config/contents/gemspec/ruby_version_globals_usage.md

@@ -0,0 +1,21 @@
+Checks that `RUBY_VERSION` constant is not used in gemspec.
+Using `RUBY_VERSION` is dangerous because value of the
+constant is determined by `rake release`.
+It's possible to have dependency based on ruby version used
+to execute `rake release` and not user's ruby version.
+
+### Example:
+
+    # bad
+    Gem::Specification.new do |spec|
+      if RUBY_VERSION >= '2.5'
+        spec.add_runtime_dependency 'gem_a'
+      else
+        spec.add_runtime_dependency 'gem_b'
+      end
+    end
+
+    # good
+    Gem::Specification.new do |spec|
+      spec.add_runtime_dependency 'gem_a'
+    end

config/contents/layout/access_modifier_indentation.md

@@ -1,5 +1,6 @@
-Modifiers should be indented as deep as method definitions, or as deep
-as the class/module keyword, depending on configuration.
+Bare access modifiers (those not applying to specific methods) should be
+indented as deep as method definitions, or as deep as the class/module
+keyword, depending on configuration.
 
 ### Example: EnforcedStyle: indent (default)
     # bad

config/contents/layout/argument_alignment.md

@@ -0,0 +1,34 @@
+Here we check if the arguments on a multi-line method
+definition are aligned.
+
+### Example: EnforcedStyle: with_first_argument (default)
+    # good
+
+    foo :bar,
+        :baz
+
+    foo(
+      :bar,
+      :baz
+    )
+
+    # bad
+
+    foo :bar,
+      :baz
+
+    foo(
+      :bar,
+        :baz
+    )
+
+### Example: EnforcedStyle: with_fixed_indentation
+    # good
+
+    foo :bar,
+      :baz
+
+    # bad
+
+    foo :bar,
+        :baz

config/contents/layout/array_alignment.md

@@ -0,0 +1,30 @@
+Here we check if the elements of a multi-line array literal are
+aligned.
+
+### Example: EnforcedStyle: with_first_element (default)
+    # good
+
+    array = [1, 2, 3,
+             4, 5, 6]
+    array = ['run',
+             'forrest',
+             'run']
+
+    # bad
+
+    array = [1, 2, 3,
+      4, 5, 6]
+    array = ['run',
+         'forrest',
+         'run']
+
+### Example: EnforcedStyle: with_fixed_indentation
+    # good
+
+    array = [1, 2, 3,
+      4, 5, 6]
+
+    # bad
+
+    array = [1, 2, 3,
+             4, 5, 6]

config/contents/layout/assignment_indentation.md

@@ -0,0 +1,18 @@
+This cop checks the indentation of the first line of the
+right-hand-side of a multi-line assignment.
+
+### Example:
+    # bad
+    value =
+    if foo
+      'bar'
+    end
+
+    # good
+    value =
+      if foo
+        'bar'
+      end
+
+The indentation of the remaining lines can be corrected with
+other cops such as `IndentationConsistency` and `EndAlignment`.