document return values, other doc tweaks

Author: carljm

Doc/c-api/perfmaps.rst

@@ -23,9 +23,12 @@ Note that holding the Global Interpreter Lock (GIL) is not required for these AP
    Open the ``/tmp/perf-$pid.map`` file, unless it's already opened, and create
    a lock to ensure thread-safe writes to the file (provided the writes are
    done through :c:func:`PyUnstable_WritePerfMapEntry`). Normally, there's no need
-   to call this explicitly, and it is safe to directly use :c:func:`PyUnstable_WritePerfMapEntry`
-   in your code. If the state isn't already initialized, it will be created on
-   the first call.
+   to call this explicitly; just use :c:func:`PyUnstable_WritePerfMapEntry`
+   and it will initialize the state on first call.
+
+   Returns ``0`` on success, ``-1`` on failure to create/open the perf map file,
+   or ``-2`` on failure to create a lock. Check :c:data:`errno` for more
+   information about the cause of a failure.
 
 .. c:function:: int PyUnstable_WritePerfMapEntry(const void *code_addr, unsigned int code_size, const char *entry_name)
 
@@ -35,12 +38,13 @@ Note that holding the Global Interpreter Lock (GIL) is not required for these AP
       # address      size  name
       7f3529fcf759 b     py::bar:/run/t.py
 
-   Extensions are encouraged to directly call this API when needed, instead of
-   separately initializing the state by calling :c:func:`PyUnstable_PerfMapState_Init`.
+   Will call :c:func:`PyUnstable_PerfMapState_Init` before writing the entry, if
+   the perf map file is not already opened. Returns ``0`` on success, or the
+   same error codes as :c:func:`PyUnstable_PerfMapState_Init` on failure.
 
-.. c:function:: int PyUnstable_PerfMapState_Fini(void)
+.. c:function:: void PyUnstable_PerfMapState_Fini(void)
 
-   Close the perf map file, which was opened in ``PyUnstable_PerfMapState_Init``. This
-   API is called by the runtime itself, during interpreter shut-down. In general,
-   there shouldn't be a reason to explicitly call this, except to handle specific
-   scenarios such as forking.
+   Close the perf map file opened by :c:func:`PyUnstable_PerfMapState_Init`.
+   This is called by the runtime itself during interpreter shut-down. In
+   general, there shouldn't be a reason to explicitly call this, except to
+   handle specific scenarios such as forking.