Clarify the reasons why pickle is almost always better than marshal

diff --git a/Doc/library/marshal.rst b/Doc/library/marshal.rst
index 6927067ab6bccaa3e33ce3f028fbed42c877dc05..8efcbb769df5b3d0bbfc16b871cdfb24dbdb65d3 100644 (file)
--- a/Doc/library/marshal.rst
+++ b/Doc/library/marshal.rst
@@ -25,7 +25,9 @@ transfer of Python objects through RPC calls, see the modules :mod:`pickle` and
 writing the "pseudo-compiled" code for Python modules of :file:`.pyc` files.
 Therefore, the Python maintainers reserve the right to modify the marshal format
 in backward incompatible ways should the need arise.  If you're serializing and
-de-serializing Python objects, use the :mod:`pickle` module instead.
+de-serializing Python objects, use the :mod:`pickle` module instead -- the
+performance is comparable, version independence is guaranteed, and pickle
+supports a substantially wider range of objects than marshal.
 
 .. warning::
 
@@ -42,6 +44,12 @@ and dictionaries are only supported as long as the values contained therein are
 themselves supported; and recursive lists and dictionaries should not be written
 (they will cause infinite loops).
 
+.. warning::
+
+   Some unsupported types such as subclasses of builtins will appear to marshal
+   and unmarshal correctly, but in fact, their type will change and the
+   additional subclass functionality and instance attributes will be lost.
+
 .. warning::
    
    On machines where C's ``long int`` type has more than 32 bits (such as the