update ActiveModel::SecurePassword docs [ci skip]

1 files changed, 38 insertions, 18 deletions

diff --git a/activemodel/lib/active_model/secure_password.rb b/activemodel/lib/active_model/secure_password.rb
index 3eab745c89..15172d21dc 100644
--- a/activemodel/lib/active_model/secure_password.rb
+++ b/activemodel/lib/active_model/secure_password.rb
@@ -6,12 +6,12 @@ module ActiveModel
       # Adds methods to set and authenticate against a BCrypt password.
       # This mechanism requires you to have a password_digest attribute.
       #
-      # Validations for presence of password on create, confirmation of password (using
-      # a "password_confirmation" attribute) are automatically added.
-      # If you wish to turn off validations, pass 'validations: false' as an argument.
-      # You can add more validations by hand if need be.
+      # Validations for presence of password on create, confirmation of password
+      # (using a +password_confirmation+ attribute) are automatically added. If
+      # you wish to turn off validations, pass <tt>validations: false</tt> as an
+      # argument. You can add more validations by hand if need be.
       #
-      # You need to add bcrypt-ruby (~> 3.0.0) to Gemfile to use has_secure_password:
+      # You need to add bcrypt-ruby (~> 3.0.0) to Gemfile to use  #has_secure_password:
       #
       #   gem 'bcrypt-ruby', '~> 3.0.0'
       #
@@ -22,35 +22,36 @@ module ActiveModel
       #     has_secure_password
       #   end
       #
-      #   user = User.new(:name => "david", :password => "", :password_confirmation => "nomatch")
+      #   user = User.new(name: 'david', password: '', password_confirmation: 'nomatch')
       #   user.save                                                      # => false, password required
-      #   user.password = "mUc3m00RsqyRe"
+      #   user.password = 'mUc3m00RsqyRe'
       #   user.save                                                      # => false, confirmation doesn't match
-      #   user.password_confirmation = "mUc3m00RsqyRe"
+      #   user.password_confirmation = 'mUc3m00RsqyRe'
       #   user.save                                                      # => true
-      #   user.authenticate("notright")                                  # => false
-      #   user.authenticate("mUc3m00RsqyRe")                             # => user
-      #   User.find_by_name("david").try(:authenticate, "notright")      # => false
-      #   User.find_by_name("david").try(:authenticate, "mUc3m00RsqyRe") # => user
+      #   user.authenticate('notright')                                  # => false
+      #   user.authenticate('mUc3m00RsqyRe')                             # => user
+      #   User.find_by_name('david').try(:authenticate, 'notright')      # => false
+      #   User.find_by_name('david').try(:authenticate, 'mUc3m00RsqyRe') # => user
       def has_secure_password(options = {})
         # Load bcrypt-ruby only when has_secure_password is used.
-        # This is to avoid ActiveModel (and by extension the entire framework) being dependent on a binary library.
+        # This is to avoid ActiveModel (and by extension the entire framework)
+        # being dependent on a binary library.
         gem 'bcrypt-ruby', '~> 3.0.0'
         require 'bcrypt'
 
         attr_reader :password
-        
+
         if options.fetch(:validations, true)
           validates_confirmation_of :password
           validates_presence_of     :password, :on => :create
         end
-        
+
         before_create { raise "Password digest missing on new record" if password_digest.blank? }
 
         include InstanceMethodsOnActivation
 
         if respond_to?(:attributes_protected_by_default)
-          def self.attributes_protected_by_default
+          def self.attributes_protected_by_default #:nodoc:
             super + ['password_digest']
           end
         end
@@ -58,13 +59,32 @@ module ActiveModel
     end
 
     module InstanceMethodsOnActivation
-      # Returns self if the password is correct, otherwise false.
+      # Returns +self+ if the password is correct, otherwise +false+.
+      #
+      #   class User < ActiveRecord::Base
+      #     has_secure_password validations: false
+      #   end
+      #
+      #   user = User.new(name: 'david', password: 'mUc3m00RsqyRe')
+      #   user.save
+      #   user.authenticate('notright')      # => false
+      #   user.authenticate('mUc3m00RsqyRe') # => user
       def authenticate(unencrypted_password)
         BCrypt::Password.new(password_digest) == unencrypted_password && self
       end
 
-      # Encrypts the password into the password_digest attribute, only if the
+      # Encrypts the password into the +password_digest+ attribute, only if the
       # new password is not blank.
+      #
+      #   class User < ActiveRecord::Base
+      #     has_secure_password validations: false
+      #   end
+      #
+      #   user = User.new
+      #   user.password = nil
+      #   user.password_digest # => nil
+      #   user.password = 'mUc3m00RsqyRe'
+      #   user.password_digest # => "$2a$10$4LEA7r4YmNHtvlAvHhsYAeZmk/xeUVtMTYqwIvYY76EW5GUqDiP4."
       def password=(unencrypted_password)
         unless unencrypted_password.blank?
           @password = unencrypted_password