Merge pull request #174 from nevir/refactor/deduplicate-documentation

Deduplicate documentation

Rakefile

@@ -1,5 +1,8 @@
+require 'open3'
+
 require 'bundler'
 require 'bundler/gem_tasks'
+
 begin
   Bundler.setup(:default, :development)
 rescue Bundler::BundlerError => e
@@ -27,4 +30,19 @@ task :internal_investigation do
   abort('RuboCop failed!') unless result.zero?
 end
 
-task default: [:spec, :internal_investigation]
+desc 'Build config/default.yml'
+task :build_config do
+  sh('bin/build_config')
+end
+
+desc 'Confirm config/default.yml is up to date'
+task confirm_config: :build_config do
+  _, stdout, _, process =
+    Open3.popen3('git diff --exit-code config/default.yml')
+
+  unless process.value.success?
+    raise "default.yml is out of sync:\n\n#{stdout.read}\nRun bin/build_config"
+  end
+end
+
+task default: [:build_config, :spec, :internal_investigation, :confirm_config]

bin/build_config

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift(File.join(__dir__, '..', 'lib'))
+
+require 'yard'
+
+require 'rubocop/rspec/description_extractor'
+require 'rubocop/rspec/config_formatter'
+
+glob = File.join(__dir__, '..', 'lib', 'rubocop', 'cop', 'rspec', '*.rb')
+YARD.parse(Dir[glob], [])
+
+descriptions = RuboCop::RSpec::DescriptionExtractor.new(YARD::Registry.all).to_h
+current_config = YAML.load_file('config/default.yml')
+
+File.write(
+  'config/default.yml',
+  RuboCop::RSpec::ConfigFormatter.new(current_config, descriptions).dump
+)

config/default.yml

@@ -1,21 +1,20 @@
+---
 AllCops:
   RSpec:
     Patterns:
-    # Match any file that contains `_spec.rb` so that FilePath can also flag
-    # and correct files with odd extensions like `spec/foo_spec.rb.html`
-    - '_spec.rb'
-    - '(?:^|/)spec/'
+    - _spec.rb
+    - "(?:^|/)spec/"
 
 RSpec/AnyInstance:
-  Description: 'Check that instances are not being stubbed globally'
+  Description: Check that instances are not being stubbed globally.
   Enabled: true
 
 RSpec/BeEql:
-  Description: 'Check for expectations where `be(...)` can be used instead of `eql(...)`'
+  Description: Check for expectations where `be(...)` can replace `eql(...)`.
   Enabled: true
 
 RSpec/HookArgument:
-  Description: 'Check the arguments passed to `before`, `around`, and `after`.'
+  Description: Checks the arguments passed to `before`, `around`, and `after`.
   Enabled: true
   EnforcedStyle: implicit
   SupportedStyles:
@@ -24,20 +23,20 @@ RSpec/HookArgument:
   - example
 
 RSpec/DescribeClass:
-  Description: 'Check that the first argument to the top level describe is the tested class or module.'
+  Description: Check that the first argument to the top level describe is a constant.
   Enabled: true
 
 RSpec/DescribedClass:
-  Description: 'Use `described_class` for tested class / module'
+  Description: Checks that tests use `described_class`.
   SkipBlocks: false
   Enabled: true
 
 RSpec/DescribeMethod:
-  Description: 'Checks that the second argument to top level describe is the tested method name.'
+  Description: Checks that the second argument to `describe` specifies a method.
   Enabled: true
 
 RSpec/ExampleWording:
-  Description: 'Do not use should when describing your tests.'
+  Description: Checks that example descriptions do not start with "should".
   Enabled: true
   CustomTransform:
     be: is
@@ -46,82 +45,82 @@ RSpec/ExampleWording:
   IgnoredWords: []
 
 RSpec/EmptyExampleGroup:
-  Description: 'Checks for `describe` and `context` groups without tests.'
+  Description: Checks if an example group does not include any tests.
   Enabled: true
   CustomIncludeMethods: []
 
 RSpec/ExpectActual:
-  Description: 'Checks for `expect(...)` calls containing literal values'
+  Description: Checks for `expect(...)` calls containing literal values.
   Enabled: true
 
 RSpec/MultipleDescribes:
-  Description: 'Checks for multiple top level describes.'
+  Description: Checks for multiple top level describes.
   Enabled: true
 
 RSpec/MultipleExpectations:
-  Description: 'Checks for multiple `expect(...)` calls in one example.'
+  Description: Checks if examples contain too many `expect` calls.
   Enabled: true
   Max: 1
 
 RSpec/NestedGroups:
-  Description: 'Checks for multiple levels of context nesting.'
+  Description: Checks for nested example groups.
   Enabled: true
   MaxNesting: 2
 
 RSpec/InstanceVariable:
-  Description: 'Checks for the usage of instance variables.'
+  Description: Checks for instance variable usage in specs.
   AssignmentOnly: false
   Enabled: true
 
 RSpec/LetSetup:
-  Description: 'Checks for `let!` being used for test setup.'
+  Description: Checks unreferenced `let!` calls being used for test setup.
   Enabled: true
 
 RSpec/LeadingSubject:
-  Description: 'Checks for `subject` definitions that come after `let` definitions.'
+  Description: Checks for `subject` definitions that come after `let` definitions.
   Enabled: true
 
 RSpec/FilePath:
-  Description: 'Checks the file and folder naming of the spec file.'
+  Description: Checks that spec file paths are consistent with the test subject.
   Enabled: true
   CustomTransform:
     RuboCop: rubocop
     RSpec: rspec
 
 RSpec/VerifiedDoubles:
-  Description: 'Prefer using verifying doubles over normal doubles.'
+  Description: Prefer using verifying doubles over normal doubles.
   Enabled: true
   IgnoreSymbolicNames: false
 
 RSpec/NotToNot:
-  Description: 'Enforces the usage of the same method on all negative message expectations.'
+  Description: Checks for consistent method usage for negating expectations.
   EnforcedStyle: not_to
   SupportedStyles:
-    - not_to
-    - to_not
+  - not_to
+  - to_not
   Enabled: true
 
 RSpec/Focus:
-  Description: 'Checks if there are focused specs.'
+  Description: Checks if examples are focused.
   Enabled: true
 
 RSpec/ExampleLength:
-  Description: 'Checks for long example'
+  Description: Checks for long examples.
   Enabled: true
   Max: 5
 
 RSpec/MessageExpectation:
-  Description: 'Checks for consistent message expectation style.'
+  Description: Checks for consistent message expectation style.
   Enabled: true
   EnforcedStyle: allow
   SupportedStyles:
   - allow
   - expect
 
 RSpec/NamedSubject:
-  Description: 'Name your RSpec subject if you reference it explicitly'
+  Description: Checks for explicitly referenced test subjects.
   Enabled: true
 
 RSpec/SubjectStub:
-  Description: 'Checks for stubbed test subjects'
+  Description: Checks for stubbed test subjects.
   Enabled: true

lib/rubocop/cop/rspec/any_instance.rb

@@ -1,6 +1,8 @@
 module RuboCop
   module Cop
     module RSpec
+      # Check that instances are not being stubbed globally.
+      #
       # Prefer instance doubles over stubbing any instance of a class
       #
       # @example

lib/rubocop/cop/rspec/be_eql.rb

@@ -1,7 +1,7 @@
 module RuboCop
   module Cop
     module RSpec
-      # Check for test expectations that can use `be` instead of `eql`
+      # Check for expectations where `be(...)` can replace `eql(...)`.
       #
       # The `be` matcher compares by identity while the `eql` matcher
       # compares using `eql?`. Integers, floats, booleans, and symbols

lib/rubocop/cop/rspec/describe_class.rb

@@ -3,8 +3,7 @@
 module RuboCop
   module Cop
     module RSpec
-      # Check that the first argument to the top level describe is the tested
-      # class or module.
+      # Check that the first argument to the top level describe is a constant.
       #
       # @example
       #   # bad

lib/rubocop/cop/rspec/describe_method.rb

@@ -3,8 +3,7 @@
 module RuboCop
   module Cop
     module RSpec
-      # Checks that the second argument to the top level describe is the tested
-      # method name.
+      # Checks that the second argument to `describe` specifies a method.
       #
       # @example
       #   # bad

lib/rubocop/cop/rspec/described_class.rb

@@ -3,6 +3,8 @@
 module RuboCop
   module Cop
     module RSpec
+      # Checks that tests use `described_class`.
+      #
       # If the first argument of describe is a class, the class is exposed to
       # each example via described_class - this should be used instead of
       # repeating the class.

lib/rubocop/cop/rspec/empty_example_group.rb

@@ -3,7 +3,7 @@
 module RuboCop
   module Cop
     module RSpec
-      # Checks if an example group does not include any tests
+      # Checks if an example group does not include any tests.
       #
       # This cop is configurable using the `CustomIncludeMethods` option
       #

lib/rubocop/cop/rspec/example_length.rb

@@ -3,6 +3,8 @@
 module RuboCop
   module Cop
     module RSpec
+      # Checks for long examples.
+      #
       # A long example is usually more difficult to understand. Consider
       # extracting out some behaviour, e.g. with a `let` block, or a helper
       # method.

lib/rubocop/cop/rspec/example_wording.rb

@@ -3,8 +3,9 @@
 module RuboCop
   module Cop
     module RSpec
-      # Do not use should when describing your tests.
-      # see: http://betterspecs.org/#should
+      # Checks that example descriptions do not start with "should".
+      #
+      # @see http://betterspecs.org/#should
       #
       # The autocorrect is experimental - use with care! It can be configured
       # with CustomTransform (e.g. have => has) and IgnoredWords (e.g. only).

lib/rubocop/cop/rspec/expect_actual.rb

@@ -3,7 +3,7 @@
 module RuboCop
   module Cop
     module RSpec
-      # Checks for literal values within `expect(...)`
+      # Checks for `expect(...)` calls containing literal values.
       #
       # @example
       #   # bad

lib/rubocop/cop/rspec/file_path.rb

@@ -3,6 +3,8 @@
 module RuboCop
   module Cop
     module RSpec
+      # Checks that spec file paths are consistent with the test subject.
+      #
       # Checks the path of the spec file and enforces that it reflects the
       # described class/module and its optionally called out method.
       #

lib/rubocop/cop/rspec/focus.rb

@@ -3,7 +3,7 @@
 module RuboCop
   module Cop
     module RSpec
-      # Checks if test is focused.
+      # Checks if examples are focused.
       #
       # @example
       #   # bad

lib/rubocop/cop/rspec/hook_argument.rb

@@ -3,6 +3,8 @@
 module RuboCop
   module Cop
     module RSpec
+      # Checks the arguments passed to `before`, `around`, and `after`.
+      #
       # This cop checks for consistent style when specifying RSpec
       # hooks which run for each example. There are three supported
       # styles: "implicit", "each", and "example." All styles have

lib/rubocop/cop/rspec/instance_variable.rb

@@ -3,8 +3,7 @@
 module RuboCop
   module Cop
     module RSpec
-      # When you have to assign a variable instead of using an instance
-      # variable, use let.
+      # Checks for instance variable usage in specs.
       #
       # This cop can be configured with the option `AssignmentOnly` which
       # will configure the cop to only register offenses on instance

lib/rubocop/cop/rspec/leading_subject.rb

@@ -3,7 +3,7 @@
 module RuboCop
   module Cop
     module RSpec
-      # Declare test subject before let declarations
+      # Checks for `subject` definitions that come after `let` definitions.
       #
       # @example
       #   # bad

lib/rubocop/cop/rspec/let_setup.rb

@@ -3,7 +3,7 @@
 module RuboCop
   module Cop
     module RSpec
-      # Detect unreferenced `let!` calls being used for test setup
+      # Checks unreferenced `let!` calls being used for test setup.
       #
       # @example
       #   # Bad

lib/rubocop/cop/rspec/message_expectation.rb

@@ -3,7 +3,7 @@
 module RuboCop
   module Cop
     module RSpec
-      # Checks specs for consistent message expectation style
+      # Checks for consistent message expectation style.
       #
       # This cop can be configured in your configuration using the
       # `EnforcedStyle` option and supports `--auto-gen-config`.

lib/rubocop/cop/rspec/multiple_describes.rb

@@ -3,8 +3,10 @@
 module RuboCop
   module Cop
     module RSpec
-      # Checks for multiple top level describes. They should be nested if it is
-      # for the same class or module or separated into different files.
+      # Checks for multiple top level describes.
+      #
+      # Multiple descriptions for the same class or module should either
+      # be nested or separated into different test files.
       #
       # @example
       #   # bad

lib/rubocop/cop/rspec/multiple_expectations.rb

@@ -3,7 +3,7 @@
 module RuboCop
   module Cop
     module RSpec
-      # Checks if examples contain too many `expect` calls
+      # Checks if examples contain too many `expect` calls.
       #
       # @see http://betterspecs.org/#single Single expectation test
       #

lib/rubocop/cop/rspec/named_subject.rb

@@ -3,7 +3,14 @@
 module RuboCop
   module Cop
     module RSpec
-      # Give `subject` a descriptive name if you reference it directly
+      # Checks for explicitly referenced test subjects.
+      #
+      # RSpec lets you declare an "implicit subject" using `subject { ... }`
+      # which allows for tests like `it { should be_valid }`. If you need to
+      # reference your test subject you should explicitly name it using
+      # `subject(:your_subject_name) { ... }`. Your test subjects should be
+      # the most important object in your tests so they deserve a descriptive
+      # name.
       #
       # @example
       #   # bad