Rescrape docs, update spec exclusion list

Author: wfleming

config/contents/lint/assignment_in_condition.md

@@ -0,0 +1,2 @@
+This cop checks for assignments in the conditions of
+if/while/until.

config/contents/lint/block_alignment.md

@@ -1,8 +1,33 @@
 This cop checks whether the end keywords are aligned properly for do
 end blocks.
 
+Three modes are supported through the `AlignWith` configuration
+parameter:
+
+`start_of_block` : the `end` shall be aligned with the
+start of the line where the `do` appeared.
+
+`start_of_line` : the `end` shall be aligned with the
+start of the line where the expression started.
+
+`either` (which is the default) : the `end` is allowed to be in either
+location. The autofixer will default to `start_of_line`.
+
 ### Example:
 
+    # either
     variable = lambda do |i|
       i
+    end
+
+    # start_of_block
+    foo.bar
+      .each do
+         baz
+       end
+
+    # start_of_line
+    foo.bar
+      .each do
+         baz
     end

config/contents/lint/debugger.md

@@ -0,0 +1 @@
+This cop checks for calls to debugger or pry.

config/contents/lint/deprecated_class_methods.md

@@ -0,0 +1 @@
+This cop checks for uses of the deprecated class method usages.

config/contents/lint/duplicate_case_condition.md

@@ -0,0 +1,12 @@
+This cop checks that there are no repeated conditions
+used in case 'when' expressions.
+
+### Example:
+
+     # bad
+     case x
+     when 'first'
+       do_something
+     when 'first'
+       do_something_else
+     end

config/contents/lint/empty_ensure.md

@@ -0,0 +1 @@
+This cop checks for empty `ensure` blocks

config/contents/lint/empty_expression.md

@@ -0,0 +1,9 @@
+This cop checks for the presence of empty expressions.
+
+### Example:
+
+    # bad
+    foo = ()
+    if ()
+      bar
+    end

config/contents/lint/empty_when.md

@@ -0,0 +1,9 @@
+This cop checks for the presence of `when` branches without a body.
+
+### Example:
+
+    # bad
+    case foo
+    when bar then 1
+    when baz then # nothing
+    end

config/contents/lint/end_in_method.md

@@ -0,0 +1 @@
+This cop checks for END blocks in method definitions.

config/contents/lint/ensure_return.md

@@ -0,0 +1 @@
+This cop checks for *return* from an *ensure* block.

config/contents/lint/eval.md

@@ -0,0 +1 @@
+This cop checks for the use of *Kernel#eval*.

config/contents/lint/handle_exceptions.md

@@ -0,0 +1 @@
+This cop checks for *rescue* blocks with no body.

config/contents/lint/inherit_exception.md

@@ -0,0 +1,26 @@
+This cop looks for error classes inheriting from `Exception`
+and its standard library subclasses, excluding subclasses of
+`StandardError`. It is configurable to suggest using either
+`RuntimeError` (default) or `StandardError` instead.
+
+### Example:
+
+    # bad
+
+    class C < Exception; end
+
+### Example:
+
+    # EnforcedStyle: runtime_error (default)
+
+    # good
+
+    class C < RuntimeError; end
+
+### Example:
+
+    # EnforcedStyle: standard_error
+
+    # good
+
+    class C < StandardError; end

config/contents/lint/loop.md

@@ -0,0 +1 @@
+This cop checks for uses of *begin...end while/until something*.

config/contents/lint/percent_string_array.md

@@ -0,0 +1,7 @@
+This cop checks for quotes and commas in %w, e.g.
+
+    `%w('foo', "bar")`
+
+it is more likely that the additional characters are unintended (for
+example, mistranslating an array of literals to percent string notation)
+rather than meant to be part of the resulting strings.

config/contents/lint/percent_symbol_array.md

@@ -0,0 +1,7 @@
+This cop checks for colons and commas in %i, e.g.
+
+    `%i(:foo, :bar)`
+
+it is more likely that the additional characters are unintended (for
+example, mistranslating an array of literals to percent string notation)
+rather than meant to be part of the resulting symbols.

config/contents/lint/rescue_exception.md

@@ -0,0 +1 @@
+This cop checks for *rescue* blocks targeting the Exception class.

config/contents/lint/shadowed_exception.md

@@ -0,0 +1,22 @@
+This cop checks for a rescued exception that get shadowed by a
+less specific exception being rescued before a more specific
+exception is rescued.
+
+### Example:
+    # bad
+    begin
+      something
+    rescue Exception
+      handle_exception
+    rescue StandardError
+      handle_standard_error
+    end
+
+    # good
+    begin
+      something
+    rescue StandardError
+      handle_standard_error
+    rescue Exception
+      handle_exception
+    end

config/contents/lint/shadowing_outer_local_variable.md

@@ -0,0 +1,4 @@
+This cop looks for use of the same name as outer local variables
+for block arguments or block local variables.
+This is a mimic of the warning
+"shadowing outer local variable - foo" from `ruby -cw`.

config/contents/lint/syntax.md

@@ -0,0 +1,2 @@
+This is actually not a cop and inspects nothing. It just provides
+methods to repack Parser's diagnostics/errors into RuboCop's offenses.

config/contents/lint/underscore_prefixed_variable_name.md

@@ -0,0 +1,2 @@
+This cop checks for underscore-prefixed variables that are actually
+used.

config/contents/lint/unified_integer.md

@@ -0,0 +1,9 @@
+This cop checks for using Fixnum or Bignum constant.
+
+### Example:
+    # bad
+    1.is_a?(Fixnum)
+    1.is_a?(Bignum)
+
+    # good
+    1.is_a?(Integer)

config/contents/lint/unneeded_disable.md

@@ -0,0 +1,9 @@
+This cop detects instances of rubocop:disable comments that can be
+removed without causing any offenses to be reported. It's implemented
+as a cop in that it inherits from the Cop base class and calls
+add_offense. The unusual part of its implementation is that it doesn't
+have any on_* methods or an investigate method. This means that it
+doesn't take part in the investigation phase when the other cops do
+their work. Instead, it waits until it's called in a later stage of the
+execution. The reason it can't be implemented as a normal cop is that
+it depends on the results of all other cops to do its work.

config/contents/lint/unneeded_splat_expansion.md

@@ -0,0 +1,41 @@
+This cop checks for unneeded usages of splat expansion
+
+### Example:
+    # bad
+    a = *[1, 2, 3]
+    a = *'a'
+    a = *1
+
+    begin
+      foo
+    rescue *[StandardError, ApplicationError]
+      bar
+    end
+
+    case foo
+    when *[1, 2, 3]
+      bar
+    else
+      baz
+    end
+
+    # good
+    c = [1, 2, 3]
+    a = *c
+    a, b = *c
+    a, *b = *c
+    a = *1..10
+    a = ['a']
+
+    begin
+      foo
+    rescue StandardError, ApplicationError
+      bar
+    end
+
+    case foo
+    when *[1, 2, 3]
+      bar
+    else
+      baz
+    end

config/contents/lint/unreachable_code.md

@@ -1,18 +1,3 @@
-This cop checks for code that will never run, because it follows a flow control
-statement such as `return` or `raise`.
-
-### Example:
-
-    # bad
-    def sad
-      raise RuntimeError
-
-      puts "This line will never be reached, so why even include it?"
-    end
-
-    # good
-    def happy
-      raise RuntimeError if problem?
-
-      puts "This line of code will sometimes be reached"
-    end
+This cop checks for unreachable code.
+The check are based on the presence of flow of control
+statement in non-final position in *begin*(implicit) blocks.

config/contents/lint/unused_block_argument.md

@@ -2,6 +2,30 @@ This cop checks for unused block arguments.
 
 ### Example:
 
-    do_something do |used, unused, _unused_but_allowed|
+    #good
+
+    do_something do |used, unused|
+      puts used
+    end
+
+    do_something do
+      puts :foo
+    end
+
+    define_method(:foo) do |_bar|
+      puts :baz
+    end
+
+    # bad
+
+    do_something do |used, _unused|
       puts used
+    end
+
+    do_something do |bar|
+      puts :foo
+    end
+
+    define_method(:foo) do |bar|
+      puts :baz
     end

config/contents/lint/useless_access_modifier.md

@@ -1,18 +1,75 @@
-This cop checks for redundant access modifiers, including those with
-no code, those which are repeated, and leading `public` modifiers in
-a class or module body.
+This cop checks for redundant access modifiers, including those with no
+code, those which are repeated, and leading `public` modifiers in a
+class or module body. Conditionally-defined methods are considered as
+always being defined, and thus access modifiers guarding such methods
+are not redundant.
 
 ### Example:
 
     class Foo
-      public # this is redundant
+      public # this is redundant (default access is public)
 
       def method
       end
 
-      private # this is not redundant
+      private # this is not redundant (a method is defined)
       def method2
       end
 
-      private # this is redundant
+      private # this is redundant (no following methods are defined)
+    end
+
+### Example:
+
+    class Foo
+      # The following is not redundant (conditionally defined methods are
+      # considered as always defining a method)
+      private
+
+      if condition?
+        def method
+        end
+      end
+
+      protected # this is not redundant (method is defined)
+
+      define_method(:method2) do
+      end
+
+      protected # this is redundant (repeated from previous modifier)
+
+      [1,2,3].each do |i|
+        define_method("foo#{i}") do
+        end
+      end
+
+      # The following is redundant (methods defined on the class'
+      # singleton class are not affected by the public modifier)
+      public
+
+      def self.method3
+      end
+    end
+
+### Example:
+    # Lint/UselessAccessModifier:
+    #   ContextCreatingMethods:
+    #     - concerning
+    require 'active_support/concern'
+    class Foo
+      concerning :Bar do
+        def some_public_method
+        end
+
+        private
+
+        def some_private_method
+        end
+      end
+
+      # this is not redundant because `concerning` created its own context
+      private
+
+      def some_other_private_method
+      end
     end

config/contents/lint/useless_assignment.md

@@ -0,0 +1,9 @@
+This cop checks for every useless assignment to local variable in every
+scope.
+The basic idea for this cop was from the warning of `ruby -cw`:
+
+    assigned but unused variable - foo
+
+Currently this cop has advanced logic that detects unreferenced
+reassignments and properly handles varied cases such as branch, loop,
+rescue, ensure, etc.