Jim Jewett posted the message msg204618 to the issue #18874 which is now closed, so I'm opening a new issue. Copy of his message.


These comments refer to http://hg.python.org/cpython/file/5c9af8194d3b/Doc/library/tracemalloc.rst which is newer than the current patches.

I believe I have consolidated the still-open issues that I see (including those that aren't mine) for this file:

http://hg.python.org/cpython/file/5c9af8194d3b/Doc/library/tracemalloc.rst

(line 24, new comment; also repeated at line 315)

frame (1 frame). To store 25 frames at startup: set the
:envvar:`PYTHONTRACEMALLOC` environment variable to ``25``, or use the
:option:`-X` ``tracemalloc=25`` command line option.
->

frame (1 frame). To store 25 frames at startup: set the
:envvar:`PYTHONTRACEMALLOC` environment variable to ``25``, or use the
:option:`-X` ``tracemalloc=25`` command line option.  If tracing is

started later, the maximum number of frames is a parameter to the 

 :func:`start` function.



(line 111)

If the system has little free memory, snapshots can be written on disk using
the :meth:`Snapshot.dump` method to analyze the snapshot offline. Then use the
:meth:`Snapshot.load` method reload the snapshot.

 ->

Snapshots can be stored to disk using :meth:`Snapshot.dump` and reloaded using :meth:`Snapshot.load`.



(line 180, new comment)
... The traceback is
where the :mod:`importlib` loaded data most recently: on the ``import pdb``
line of the :mod:`doctest` module. The traceback may change if a new module is
loaded.

->

The traceback represents the call stack when those allocations were made.  

As this particular summary is itemized by traceback, it also represents 

the call stack for all 903 of those allocations.


(line 252: new comment)
.. function:: clear_traces()

   Clear traces of memory blocks allocated by Python.

Add "Future allocations will still be traced."


Is this just a shortcut for stop();start()  ?  If so, please say so.  If not, please explain why.



(Line 311: new comment)
to measure how much memory is used
->
for an approximate measure of how much memory is used


I understand your reluctance to get into too many details, but ... well, it isn't a complete measure.  It misses the python objects of tracemalloc itself, it misses the overhead of the module, it misses any filenames that were kept alive only by tracing, etc.


(Line 372, new comment)
      If *inclusive* is ``True`` (include), only trace memory blocks allocated
      in a file with a name matching :attr:`filename_pattern` at line number
      :attr:`lineno`.

      If *inclusive* is ``False`` (exclude), ignore memory blocks allocated in
      a file with a name matching :attr:`filename_pattern` at line number
      :attr:`lineno`.
->
      If *inclusive* is ``True`` (include), then trace memory blocks allocated
      in a file with a name matching :attr:`filename_pattern` at line number
      :attr:`lineno`.  Also excludes any blocks not selected by any filter.

      If *inclusive* is ``False`` (exclude), ignore memory blocks allocated in
      a file with a name matching :attr:`filename_pattern` at line number
      :attr:`lineno`, even if they would otherwise be included.


(Line 394: new comment)
      This attribute is ignored if the traceback limit is less than ``2``.
->
      This attribute is meaningless if the traceback limit is ``1``.



Just after Line 428, not quite a new issue:
      Compute the differences with an old snapshot. Get statistics as a sorted
      list of :class:`StatisticDiff` instances grouped by *group_by*.

->

      Compute the differences with an old snapshot. Get statistics as a sorted
      list of :class:`StatisticDiff` instances grouped by *group_by*.

      Note that applying different Filters can cause spurious differences; users planning to archive a Snapshot may therefore wish to first add various annotations.


(Line 454, new comment)
      All inclusive filters are applied at once, a trace is ignored if no
      inclusive filters match it. A trace is ignored if at least one exclusive
      filter matchs it.
->
      If there are any inclusive filters, then they are all applied, and traces which do not match at least one of them are excluded.  A trace is also ignored if at least one exclusive
      filter matches it.


Line 544, new comment:

   .. attribute:: count_diff

      Difference of number of memory blocks between the old and the new
      snapshots (``int``): ``0`` if the memory blocks have been allocated in
      the new snapshot.
->
   .. attribute:: count_diff

      Difference of number of memory blocks between the old and the new
      snapshots (``int``).  count_diff==count if the memory blocks do not appear in the old snapshot.

Line 558, similar to above:
      the new snapshots (``int``): ``0`` if the memory blocks have been
      allocated in the new snapshot.
->
      the new snapshots (``int``).  size_diff==size if the memory blocks do not appear in the old snapshot.

And copy of his second message msg204619:

Drat:  forgot one at line 277


.. function:: get_traced_memory()

   Get the current size and maximum size of memory blocks traced by the
   :mod:`tracemalloc` module as a tuple: ``(size: int, max_size: int)``.

I have a tendency to read "maximum size" as the most it is willing/able to trace, rather than the most it has traced at a single time so far.  I therefore prefer "peak_size".

Also, this doesn't suggests that the object is strictly a tuple, and that results.size or results.peak_size will not work; is that intentional?

> I have a tendency to read "maximum size" as the most it is willing/able to trace, rather than the most it has traced at a single time so far.  I therefore prefer "peak_size".

I already replied to this comment on Rietveld, I created the issue #19798 which is already fixed.

New changeset 8df54b9b99ef by Victor Stinner in branch 'default':
Issue #19818: tracemalloc, the number of frame limit cannot be zero anymore
http://hg.python.org/cpython/rev/8df54b9b99ef

Could you please write a patch on Doc/library/tracemalloc.rst? It's really hard to review your raw comments in comments.

You should probably sign the contributor agreement.
http://www.python.org/psf/contrib/contrib-form/

"""
Is [clear_traces()] just a shortcut for stop();start()  ?  If so, please say so.
"""

It's almost the same. clear_traces() does not uninstall and reinstall hooks on memory allocators. I prefer to not give too much details in the high-level documentation.

"""
Line 558, similar to above:
      the new snapshots (``int``): ``0`` if the memory blocks have been
      allocated in the new snapshot.
->
      the new snapshots (``int``).  size_diff==size if the memory blocks do not appear in the old snapshot.
"""

This is not correct, size_diff is 0 if memory blocks are new, not size.