Add documentation to MessageVerifier

[ci skip]

Complements #17727 and closes ee73d9ff.

@lleger How do you feel about this?

activesupport/lib/active_support/message_verifier.rb

@@ -34,7 +34,15 @@ def initialize(secret, options = {})
       @serializer = options[:serializer] || Marshal
     end
 
-    # FIXME: Document this method
+    # Checks if a signed message could have been generated by signing an object
+    # with the +MessageVerifier+'s secret.
+    #
+    #   verifier = ActiveSupport::MessageVerifier.new 's3Krit'
+    #   signed_message = verifier.generate 'a private message'
+    #   verifier.valid_message?(signed_message) # => true
+    #
+    #   tampered_message = signed_message.chop # editing the message invalidates the signature
+    #   verifier.valid_message?(tampered_message) # => false
     def valid_message?(signed_message)
       return if signed_message.blank?
 
@@ -42,7 +50,28 @@ def valid_message?(signed_message)
       data.present? && digest.present? && ActiveSupport::SecurityUtils.secure_compare(digest, generate_digest(data))
     end
 
-    # FIXME: Document this method
+    # Decodes the signed message using the +MessageVerifier+'s secret.
+    #
+    #   verifier = ActiveSupport::MessageVerifier.new 's3Krit'
+    #
+    #   signed_message = verifier.generate 'a private message'
+    #   verifier.verified(signed_message) #=> 'a private message'
+    #
+    # Returns +nil+ if the message was not signed with the same secret.
+    #
+    #   other_verifier = ActiveSupport::MessageVerifier.new 'd1ff3r3nt-s3Krit'
+    #   other_verifier.verified(signed_message) #=> nil
+    #
+    # Returns +nil+ if the message is not Base64-encoded.
+    #
+    #   invalid_message = "f--46a0120593880c733a53b6dad75b42ddc1c8996d"
+    #   verifier.verified(invalid_message) #=> nil
+    #
+    # Raises any error raised while decoding the signed message.
+    #
+    #   incompatible_message = "test--dad7b06c94abba8d46a15fafaef56c327665d5ff"
+    #   verifier.verified(incompatible_message) #=> TypeError: incompatible marshal file format
+    #
     def verified(signed_message)
       if valid_message?(signed_message)
         begin
@@ -55,12 +84,29 @@ def verified(signed_message)
       end
     end
 
-    # FIXME: Document this method
+    # Decodes the signed message using the +MessageVerifier+'s secret.
+    #
+    #   verifier = ActiveSupport::MessageVerifier.new 's3Krit'
+    #   signed_message = verifier.generate 'a private message'
+    #
+    #   verifier.verify(signed_message) #=> 'a private message'
+    #
+    # Raises +InvalidSignature+ if the message was not signed with the same
+    # secret or was not Base64-encoded.
+    #
+    #   other_verifier = ActiveSupport::MessageVerifier.new 'd1ff3r3nt-s3Krit'
+    #   other_verifier.verified(signed_message) #=> ActiveSupport::MessageVerifier::InvalidSignature
     def verify(signed_message)
       verified(signed_message) || raise(InvalidSignature)
     end
 
-    # FIXME: Document this method
+    # Generates a signed message for the provided value.
+    #
+    # The message is signed with the +MessageVerifier+'s secret. Without knowing
+    # the secret, the original value cannot be extracted from the message.
+    #
+    #   verifier = ActiveSupport::MessageVerifier.new 's3Krit'
+    #   verifier.generate 'a private message' # => "BAhJIhRwcml2YXRlLW1lc3NhZ2UGOgZFVA==--e2d724331ebdee96a10fb99b089508d1c72bd772"
     def generate(value)
       data = encode(@serializer.dump(value))
       "#{data}--#{generate_digest(data)}"