[DOC] Document Marshal#load parameter freeze: (#5332)

Merged-By: byroot <jean.boussier@gmail.com>

marshal.rb

@@ -1,7 +1,7 @@
 module Marshal
   # call-seq:
-  #     load( source [, proc] ) -> obj
+  #    load(source, proc = nil, freeze: false) -> obj
-  #     restore( source [, proc] ) -> obj
+  #    restore(source, proc = nil, freeze: false) -> obj
   #
   # Returns the result of converting the serialized data in source into a
   # Ruby object (possibly with associated subordinate objects). source
@@ -11,6 +11,25 @@ module Marshal
   #
   # Never pass untrusted data (including user supplied input) to this method.
   # Please see the overview for further details.
+  #
+  # If the <tt>freeze: true</tt> argument is passed, deserialized object would
+  # be deeply frozen. Note that it may lead to more efficient memory usage due to
+  # frozen strings deduplication:
+  #
+  #    serialized = Marshal.dump(['value1', 'value2', 'value1', 'value2'])
+  #
+  #    deserialized = Marshal.load(serialized)
+  #    deserialized.map(&:frozen?)
+  #    # => [false, false, false, false]
+  #    deserialized.map(&:object_id)
+  #    # => [1023900, 1023920, 1023940, 1023960] -- 4 different objects
+  #
+  #    deserialized = Marshal.load(serialized, freeze: true)
+  #    deserialized.map(&:frozen?)
+  #    # => [true, true, true, true]
+  #    deserialized.map(&:object_id)
+  #    # => [1039360, 1039380, 1039360, 1039380] -- only 2 different objects, object_ids repeating
+  #
   def self.load(source, proc = nil, freeze: false)
     Primitive.marshal_load(source, proc, freeze)
   end