Docs: Improve multiprocessing.SharedMemory reference (#114093)

Align the multiprocessing shared memory docs with Diatáxis's
recommendations for references.

- use a parameter list for the SharedMemory.__init__() argument spec
- use the imperative mode
- use versionadded, not versionchanged, for added parameters
- reflow touched lines according to SemBr

diff --git a/Doc/library/multiprocessing.shared_memory.rst b/Doc/library/multiprocessing.shared_memory.rst
index 9b5c1c32a91f558b98cf79eb5b20fd85dde7366d..2e3f5be4dd233542783280129e287cd9a3505881 100644 (file)
--- a/Doc/library/multiprocessing.shared_memory.rst
+++ b/Doc/library/multiprocessing.shared_memory.rst
@@ -38,7 +38,8 @@ copying of data.
 
 .. class:: SharedMemory(name=None, create=False, size=0, *, track=True)
 
-   Creates a new shared memory block or attaches to an existing shared
+   Create an instance of the :class:`!SharedMemory` class for either
+   creating a new shared memory block or attaching to an existing shared
    memory block.  Each shared memory block is assigned a unique name.
    In this way, one process can create a shared memory block with a
    particular name and a different process can attach to that same shared
@@ -51,41 +52,48 @@ copying of data.
    When a shared memory block is no longer needed by any process, the
    :meth:`unlink` method should be called to ensure proper cleanup.
 
-   *name* is the unique name for the requested shared memory, specified as
-   a string.  When creating a new shared memory block, if ``None`` (the
-   default) is supplied for the name, a novel name will be generated.
-
-   *create* controls whether a new shared memory block is created (``True``)
-   or an existing shared memory block is attached (``False``).
-
-   *size* specifies the requested number of bytes when creating a new shared
-   memory block.  Because some platforms choose to allocate chunks of memory
-   based upon that platform's memory page size, the exact size of the shared
-   memory block may be larger or equal to the size requested.  When attaching
-   to an existing shared memory block, the *size* parameter is ignored.
-
-   *track*, when enabled, registers the shared memory block with a resource
-   tracker process on platforms where the OS does not do this automatically.
-   The resource tracker ensures proper cleanup of the shared memory even
-   if all other processes with access to the memory exit without doing so.
-   Python processes created from a common ancestor using :mod:`multiprocessing`
-   facilities share a single resource tracker process, and the lifetime of
-   shared memory segments is handled automatically among these processes.
-   Python processes created in any other way will receive their own
-   resource tracker when accessing shared memory with *track* enabled.
-   This will cause the shared memory to be deleted by the resource tracker
-   of the first process that terminates.
-   To avoid this issue, users of :mod:`subprocess` or standalone Python
-   processes should set *track* to ``False`` when there is already another
-   process in place that does the bookkeeping.
-   *track* is ignored on Windows, which has its own tracking and
-   automatically deletes shared memory when all handles to it have been closed.
-
-   .. versionchanged:: 3.13 Added *track* parameter.
+   :param name:
+      The unique name for the requested shared memory, specified as a string.
+      When creating a new shared memory block, if ``None`` (the default)
+      is supplied for the name, a novel name will be generated.
+   :type name: str | None
+
+   :param bool create:
+      Control whether a new shared memory block is created (``True``)
+      or an existing shared memory block is attached (``False``).
+
+   :param int size:
+      The requested number of bytes when creating a new shared memory block.
+      Because some platforms choose to allocate chunks of memory
+      based upon that platform's memory page size, the exact size of the shared
+      memory block may be larger or equal to the size requested.
+      When attaching to an existing shared memory block,
+      the *size* parameter is ignored.
+
+   :param bool track:
+      When ``True``, register the shared memory block with a resource
+      tracker process on platforms where the OS does not do this automatically.
+      The resource tracker ensures proper cleanup of the shared memory even
+      if all other processes with access to the memory exit without doing so.
+      Python processes created from a common ancestor using :mod:`multiprocessing`
+      facilities share a single resource tracker process, and the lifetime of
+      shared memory segments is handled automatically among these processes.
+      Python processes created in any other way will receive their own
+      resource tracker when accessing shared memory with *track* enabled.
+      This will cause the shared memory to be deleted by the resource tracker
+      of the first process that terminates.
+      To avoid this issue, users of :mod:`subprocess` or standalone Python
+      processes should set *track* to ``False`` when there is already another
+      process in place that does the bookkeeping.
+      *track* is ignored on Windows, which has its own tracking and
+      automatically deletes shared memory when all handles to it have been closed.
+
+   .. versionadded:: 3.13
+      The *track* parameter.
 
    .. method:: close()
 
-      Closes the file descriptor/handle to the shared memory from this
+      Close the file descriptor/handle to the shared memory from this
       instance.  :meth:`close` should be called once access to the shared
       memory block from this instance is no longer needed.  Depending
       on operating system, the underlying memory may or may not be freed
@@ -94,7 +102,7 @@ copying of data.
 
    .. method:: unlink()
 
-      Deletes the underlying shared memory block.  This should be called only
+      Delete the underlying shared memory block.  This should be called only
       once per shared memory block regardless of the number of handles to it,
       even in other processes.
       :meth:`unlink` and :meth:`close` can be called in any order, but
@@ -277,7 +285,7 @@ finishes execution.
 
 .. class:: ShareableList(sequence=None, *, name=None)
 
-   Provides a mutable list-like object where all values stored within are
+   Provide a mutable list-like object where all values stored within are
    stored in a shared memory block.
    This constrains storable values to the following built-in data types:
 
@@ -334,12 +342,12 @@ finishes execution.
 
    .. method:: count(value)
 
-      Returns the number of occurrences of *value*.
+      Return the number of occurrences of *value*.
 
    .. method:: index(value)
 
-      Returns first index position of *value*.  Raises :exc:`ValueError` if
-      *value* is not present.
+      Return first index position of *value*.
+      Raise :exc:`ValueError` if *value* is not present.
 
    .. attribute:: format