[DOC] Document thread-safety of Digest algorithms

README.md

@@ -30,24 +30,24 @@ Or install it yourself as:
 require 'digest'
 
 # Compute a complete digest
-Digest::SHA256.digest 'message'       #=> "\xABS\n\x13\xE4Y..."
+Digest(:SHA256).digest 'message'       #=> "\xABS\n\x13\xE4Y..."
 
-sha256 = Digest::SHA256.new
+sha256 = Digest(:SHA256).new
 sha256.digest 'message'               #=> "\xABS\n\x13\xE4Y..."
 
 # Other encoding formats
-Digest::SHA256.hexdigest 'message'    #=> "ab530a13e459..."
-Digest::SHA256.base64digest 'message' #=> "q1MKE+RZFJgr..."
+Digest(:SHA256).hexdigest 'message'    #=> "ab530a13e459..."
+Digest(:SHA256).base64digest 'message' #=> "q1MKE+RZFJgr..."
 
 # Compute digest by chunks
-md5 = Digest::MD5.new
+md5 = Digest(:MD5).new
 md5.update 'message1'
 md5 << 'message2'                     # << is an alias for update
 
 md5.hexdigest                         #=> "94af09c09bb9..."
 
 # Compute digest for a file
-sha256 = Digest::SHA256.file 'testfile'
+sha256 = Digest(:SHA256).file 'testfile'
 sha256.hexdigest
 ```
 

ext/digest/digest.c

@@ -37,29 +37,36 @@ RUBY_EXTERN void Init_digest_base(void);
  * are also called one-way functions, it is easy to compute a digest from
  * a message, but it is infeasible to generate a message from a digest.
  *
+ * Prefer using the thread-safe <tt>Digest()</tt> method to dynamically look up
+ * an algorithm.
+ *
+ * If you are accessing an algorithm directly via its constant, ensure you
+ * explicitly require the algorithm under the <tt>digest/</tt> path (ex. <tt>digest/sha2</tt>).
+ * Relying on the constant lookup via +const_missing+ is not thread-safe.
+ *
  * == Examples
  *
  *   require 'digest'
  *
  *   # Compute a complete digest
- *   Digest::SHA256.digest 'message'       #=> "\xABS\n\x13\xE4Y..."
+ *   Digest(:SHA256).digest 'message'       #=> "\xABS\n\x13\xE4Y..."
  *
- *   sha256 = Digest::SHA256.new
+ *   sha256 = Digest(:SHA256).new
  *   sha256.digest 'message'               #=> "\xABS\n\x13\xE4Y..."
  *
  *   # Other encoding formats
- *   Digest::SHA256.hexdigest 'message'    #=> "ab530a13e459..."
- *   Digest::SHA256.base64digest 'message' #=> "q1MKE+RZFJgr..."
+ *   Digest(:SHA256).hexdigest 'message'    #=> "ab530a13e459..."
+ *   Digest(:SHA256).base64digest 'message' #=> "q1MKE+RZFJgr..."
  *
  *   # Compute digest by chunks
- *   md5 = Digest::MD5.new
+ *   md5 = Digest(:MD5).new
  *   md5.update 'message1'
  *   md5 << 'message2'                     # << is an alias for update
  *
  *   md5.hexdigest                         #=> "94af09c09bb9..."
  *
  *   # Compute digest for a file
- *   sha256 = Digest::SHA256.file 'testfile'
+ *   sha256 = Digest(:SHA256).file 'testfile'
  *   sha256.hexdigest
  *
  * Additionally digests can be encoded in "bubble babble" format as a sequence

ext/digest/md5/md5init.c

@@ -28,7 +28,7 @@ static const rb_digest_metadata_t md5 = {
  * MD5 calculates a digest of 128 bits (16 bytes).
  *
  * == Examples
- *  require 'digest'
+ *  require 'digest/md5'
  *
  *  # Compute a complete digest
  *  Digest::MD5.hexdigest 'abc'      #=> "90015098..."

ext/digest/rmd160/rmd160init.c

@@ -24,7 +24,7 @@ static const rb_digest_metadata_t rmd160 = {
  * RMD160 calculates a digest of 160 bits (20 bytes).
  *
  * == Examples
- *  require 'digest'
+ *  require 'digest/rmd160'
  *
  *  # Compute a complete digest
  *  Digest::RMD160.hexdigest 'abc'      #=> "8eb208f7..."

ext/digest/sha1/sha1init.c

@@ -30,7 +30,7 @@ static const rb_digest_metadata_t sha1 = {
  * SHA-1 calculates a digest of 160 bits (20 bytes).
  *
  * == Examples
- *  require 'digest'
+ *  require 'digest/sha1'
  *
  *  # Compute a complete digest
  *  Digest::SHA1.hexdigest 'abc'      #=> "a9993e36..."

lib/digest/sha2.rb

@@ -27,7 +27,7 @@ module Digest
   #   digest (SHA512).
   #
   # ==Examples
-  #  require 'digest'
+  #  require 'digest/sha2'
   #
   #  # Compute a complete digest
   #  Digest::SHA2.hexdigest 'abc'          # => "ba7816bf8..."