PEP 454: rename reset() to clear_traces()

Explain also in clear_traces() documentation how to get traces before clearing them.

pep-0454.txt

@@ -24,12 +24,12 @@ Classic generic tools like Valgrind can get the C traceback where a
 memory block was allocated. Using such tools to analyze Python memory
 allocations does not help because most memory blocks are allocated in
 the same C function, in ``PyMem_Malloc()`` for example. Moreover, Python
-has an allocator for small object called "pymalloc" which keeps free
+has an allocator for small objects called "pymalloc" which keeps free
 blocks for efficiency. This is not well handled by these tools.
 
 There are debug tools dedicated to the Python language like ``Heapy``
-``Pympler`` and ``Meliae`` which lists all live objects using the
+``Pympler`` and ``Meliae`` which lists all alive objects using the
-garbage module (functions like ``gc.get_objects()``,
+garbage collector module (functions like ``gc.get_objects()``,
 ``gc.get_referrers()`` and ``gc.get_referents()``), compute their size
 (ex: using ``sys.getsizeof()``) and group objects by type. These tools
 provide a better estimation of the memory usage of an application.  They
@@ -108,7 +108,7 @@ memory allocations.
 Main functions
 --------------
 
-``reset()`` function:
+``clear_traces()`` function:
 
     Clear traces of memory blocks allocated by Python.
 
@@ -120,6 +120,9 @@ Main functions
     Stop tracing Python memory allocations and clear traces of memory
     blocks allocated by Python.
 
+    Call ``get_traces()`` or ``take_snapshot()`` function to get traces
+    before clearing them.
+
     See also ``enable()`` and ``is_enabled()`` functions.
 
 
@@ -154,7 +157,7 @@ Trace functions
 ---------------
 
 When Python allocates a memory block, ``tracemalloc`` attachs a "trace" to
-it to store information on it: its size in bytes and the traceback where the
+the memory block to store its size in bytes and the traceback where the
 allocation occured.
 
 The following functions give access to these traces. A trace is a ``(size: int,
@@ -199,8 +202,8 @@ has a size of 32 bytes and was allocated at ``x.py:7``, line called from line
     ``(filename: str, lineno: int)`` tuples.
 
     The list of traces do not include memory blocks allocated before the
-    ``tracemalloc`` module was enabled and memory blocks ignored by
+    ``tracemalloc`` module was enabled nor memory blocks ignored by
-    filters (see ``get_filters()()``).
+    filters (see ``get_filters()``).
 
     Return an empty list if the ``tracemalloc`` module is disabled.
 
@@ -248,7 +251,8 @@ Filter functions
     is ignored if at least one exclusive filter matchs its trace.
 
     The new filter is not applied on already collected traces. Use the
-    ``reset()`` function to ensure that all traces match the new filter.
+    ``clear_traces()`` function to ensure that all traces match the new
+    filter.
 
 
 ``clear_filters()`` function:
@@ -284,8 +288,7 @@ Filter
     the comparison is case insensitive and the alternative separator
     ``'/'`` is replaced with the standard separator ``'\'``.
 
-    For example, use ``Filter(False, "<unknown>")`` to exclude empty
+    Use ``Filter(False, "<unknown>")`` to exclude empty tracebacks.
-    tracebacks.
 
 ``inclusive`` attribute:
 
@@ -384,7 +387,8 @@ Snapshot
     Traces of all memory blocks allocated by Python, result of the
     ``get_traces()`` function: list of ``(size: int, traceback: tuple)``
     tuples, *traceback* is a tuple of ``(filename: str, lineno: int)``
-    tuples.
+    tuples. *size* is the size of the memory block in bytes, *traceback*
+    is the Python stack where the allocation occured.
 
 ``timestamp`` attribute: