Add documentation, news for define_enum_for

NEWS.md

@@ -41,6 +41,11 @@
 * `ensure_exclusion_of` has been renamed to `validate_exclusion_of`.
   `ensure_exclusion_of` is deprecated and will be removed in 3.0.0.
 
+### Features
+
+* Add new matcher `define_enum_for` to test usage of the `enum` macro introduced
+  in Rails 4.1.
+
 # 2.6.2
 
 ### Bug fixes

README.md

@@ -35,6 +35,8 @@ complex, and error-prone.
   tests usage of the `accepts_nested_attributes_for` macro.
 * **[belong_to](lib/shoulda/matchers/active_record/association_matcher.rb)** tests
   your `belongs_to` associations.
+* **[define_enum_for](lib/shoulda/matchers/active_record/define_enum_for_matcher.rb)**
+  tests usage of the `enum` macro.
 * **[have_many](lib/shoulda/matchers/active_record/association_matcher.rb)** tests
   your `has_many` associations.
 * **[have_one](lib/shoulda/matchers/active_record/association_matcher.rb)** tests your

lib/shoulda/matchers/active_record/define_enum_for_matcher.rb

@@ -1,10 +1,56 @@
 module Shoulda
   module Matchers
     module ActiveRecord
-      def define_enum_for(name)
-        DefineEnumForMatcher.new(name)
+      # The `define_enum_for` matcher is used to test that the `enum` macro has
+      # been used to decorate an attribute with enum methods.
+      #
+      #     class Process < ActiveRecord::Base
+      #       enum status: [:running, :stopped, :suspended]
+      #     end
+      #
+      #     # RSpec
+      #     describe Process do
+      #       it { should define_enum_for(:status) }
+      #       end
+      #     end
+      #
+      #     # Test::Unit
+      #     class ProcessTest < ActiveSupport::TestCase
+      #       should define_enum_for(:status)
+      #     end
+      #
+      # #### Qualifiers
+      #
+      # ##### with
+      #
+      # Use `with` to test that the enum has been defined with a certain set of
+      # known values.
+      #
+      #     class Process < ActiveRecord::Base
+      #       enum status: [:running, :stopped, :suspended]
+      #     end
+      #
+      #     # RSpec
+      #     describe Process do
+      #       it do
+      #         should define_enum_for(:status).
+      #           with([:running, :stopped, :suspended])
+      #       end
+      #     end
+      #
+      #     # Test::Unit
+      #     class ProcessTest < ActiveSupport::TestCase
+      #       should define_enum_for(:status).
+      #         with([:running, :stopped, :suspended])
+      #     end
+      #
+      # @return [DefineEnumForMatcher]
+      #
+      def define_enum_for(attribute_name)
+        DefineEnumForMatcher.new(attribute_name)
       end
 
+      # @private
       class DefineEnumForMatcher
         def initialize(attribute_name)
           @attribute_name = attribute_name