Improvements on the enum documentation [ci skip]

The note regarding the `_prefix` and `_suffix` options is no longer
useful since they were renamed specifically for this purpose.

Also the given example doesn't show what these options enable and in
which case they are really useful (when there are conflicting values
for instance).

Refs #20999.

[Godfrey Chan & Robin Dupret]

1 files changed, 11 insertions, 9 deletions

diff --git a/activerecord/lib/active_record/enum.rb b/activerecord/lib/active_record/enum.rb
index 9c9307df15..91a13cb0cd 100644
--- a/activerecord/lib/active_record/enum.rb
+++ b/activerecord/lib/active_record/enum.rb
@@ -77,20 +77,22 @@ module ActiveRecord
   #
   # You can use the +:_prefix+ or +:_suffix+ options when you need to define
   # multiple enums with same values. If the passed value is +true+, the methods
-  # are prefixed/suffixed with the name of the enum.
+  # are prefixed/suffixed with the name of the enum. It is also possible to
+  # supply a custom value:
   #
-  #   class Invoice < ActiveRecord::Base
-  #     enum verification: [:done, :fail], _prefix: true
+  #   class Conversation < ActiveRecord::Base
+  #     enum status: [:active, :archived], _suffix: true
+  #     enum comments_status: [:active, :inactive], _prefix: :comments
   #   end
   #
-  # It is also possible to supply a custom value:
+  # With the above example, the bang and predicate methods along with the
+  # associated scopes are now prefixed and/or suffixed accordingly:
   #
-  #   class Invoice < ActiveRecord::Base
-  #     enum verification: [:done, :fail], _prefix: :verification_status
-  #   end
+  #   conversation.active_status!
+  #   conversation.archived_status? # => false
   #
-  # Note that <tt>:_prefix</tt>/<tt>:_suffix</tt> are reserved keywords and can
-  # not be used as enum names.
+  #   conversation.comments_inactive!
+  #   conversation.comments_active? # => false
 
   module Enum
     def self.extended(base) # :nodoc: