Update docs about file field serialization.

docs/source/serialization.rst

@@ -54,21 +54,28 @@ File Fields
 Download (serialization)
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
-For download, the file field will simply be serialized to a string that contains the download URL for the file.
+For download, the file field will be serialized to a mapping that contains the
+file's most basic metadata, and a hyperlink that the client can follow to
+download the file:
 
 .. code:: json
 
       {
         "...": "",
         "@type": "File",
         "title": "My file",
-        "file": "http://localhost:55001/plone/file/@@download/file"
+        "file": {
+          "content-type": "application/pdf",
+          "download": "http://localhost:55001/plone/file/@@download/file",
+          "filename": "file.pdf",
+          "size": 74429
+        }
       }
 
-That URL points to the regular Plone download view.
-
-This means that when accessing that URL, your request won't be handled by the API but a regular Plone browser view.
-Therefore you must **not** send the ``Accept: application/json`` header in this case.
+That URL in the ``download`` property points to the regular Plone download
+view. The client can send a ``GET`` request to that URL with an ``Accept``
+header containing the MIME type indicated in the ``content-type`` property,
+and will get a response containing the file.
 
 Upload (deserialization)
 ^^^^^^^^^^^^^^^^^^^^^^^^