[3.14] gh-159185: Document that PyMarshal_WriteObjectToFile can silently truncate before 3.16 (GH-159201) (#159203)

gh-159185: Document that PyMarshal_WriteObjectToFile can silently truncate before 3.16 (GH-159201)

gh-159185: Document that the PyMarshal file writers can fail silently before 3.16

In Python 3.15 and earlier, PyMarshal_WriteObjectToFile() ignores most
marshalling errors and all I/O errors: it returns without setting the
error indicator after writing only part of the data.
PyMarshal_WriteLongToFile() ignores I/O errors in the same way.  That
was fixed in 3.16 by gh-155907, which is not backported.  Tell the users
of the older versions so that they can check what was written.
(cherry picked from commit b3714a5)

Co-authored-by: Gregory P. Smith <68491+gpshead@users.noreply.github.com>

Author: miss-islington

Doc/c-api/marshal.rst

@@ -29,6 +29,12 @@ the :py:mod:`Python module documentation <marshal>` for details.
    This function can fail, in which case it sets the error indicator.
    Use :c:func:`PyErr_Occurred` to check for that.
 
+   .. note::
+
+      In Python 3.15 and earlier, this function does not set the error
+      indicator if writing to *file* fails.
+      The same caveat applies as for :c:func:`PyMarshal_WriteObjectToFile`.
+
 .. c:function:: void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version)
 
    Marshal a Python object, *value*, to *file*.
@@ -37,6 +43,17 @@ the :py:mod:`Python module documentation <marshal>` for details.
    This function can fail, in which case it sets the error indicator.
    Use :c:func:`PyErr_Occurred` to check for that.
 
+   .. note::
+
+      In Python 3.15 and earlier, this function can write only part of the
+      data to *file* and return without setting the error indicator, for
+      example if *value* contains an object which cannot be marshalled or
+      if writing to *file* fails (see :gh:`155907`).
+      Code which has to support these versions cannot rely on
+      :c:func:`PyErr_Occurred` alone to know that all the data was written.
+      It can use :c:func:`PyMarshal_WriteObjectToString` and write the
+      result itself, or validate what was written.
+
 .. c:function:: PyObject* PyMarshal_WriteObjectToString(PyObject *value, int version)
 
    Return a bytes object containing the marshalled representation of *value*.