Apply suggestions from code review

Co-authored-by: Petr Viktorin <encukou@gmail.com>

Author: ZeroIntensity

Doc/c-api/file.rst

@@ -136,10 +136,17 @@ the :mod:`io` APIs instead.
 Deprecated API
 ^^^^^^^^^^^^^^
 
-.. c:function:: PyObject *PyFile_NewStdPrinter(void)
+
+These are :term:`soft deprecated` APIs that were included in Python's C API
+by mistake. They are documented solely for completeness; use other
+``PyFile*`` APIs instead.
+
+.. c:function:: PyObject *PyFile_NewStdPrinter(int fd)
+
+   Use :c:func:`PyFile_FromFd` with defaults (``fd, NULL, "w", -1, NULL, NULL, NULL, 0``) instead.
 
 .. c:var:: PyTypeObject PyStdPrinter_Type
 
-   These are :term:`soft deprecated` APIs that were included in Python's C API
-   by mistake. They are documented solely for completeness; use other
-   ``PyFile*`` APIs instead.
+   Type of file-like objects used internally at Python startup when :py:mod:`io` is
+   not yet available.
+   Use :py:func:`io.open` or :c:func:`PyFile_FromFd` to create file objects instead.

Doc/c-api/long.rst

@@ -860,14 +860,19 @@ The :c:type:`PyLongWriter` API can be used to import an integer.
 Deprecated API
 ^^^^^^^^^^^^^^
 
-These macros are :term:`soft deprecated`. They represent internal constants
-for :c:type:`PyLongObject` instances.
+These macros are :term:`soft deprecated`. They describe parameters
+of the internal representation of :c:type:`PyLongObject` instances.
+
+Use :c:func:`PyLong_GetNativeLayout` instead, along with :c:func:`PyLongExport` and
+:c:type:`PyLongWriter` to access integer data.
+These currently use the same layout, but are designed to continue working correctly
+even if CPython's internal integer representation changes.
 
-Do not use these; use :c:func:`PyLong_GetNativeLayout` instead.
 
 .. c:macro:: PyLong_SHIFT
 
-   This is currently equivalent to ``30``.
+   This is equivalent to :c:member:`~PyLongLayout.bits_per_digit` in
+   the output of :c:func:`PyLong_GetNativeLayout`.
 
 
 .. c:macro:: PyLong_BASE
@@ -877,4 +882,4 @@ Do not use these; use :c:func:`PyLong_GetNativeLayout` instead.
 
 .. c:macro:: PyLong_MASK
 
-   This is currently equivalent to :c:expr:`PyLong_BASE - 1`
+   This is currently equivalent to :c:expr:`(1 << PyLong_SHIFT) - 1`