whatsnew for gc.get_stats, plus doc tweaks.

Clarified the "At the moment" wording, and added the get_stats entry in the
module summary that Serhiy noted was missing at the end of issue 16351.

Given that pydoc lists all the function docstrings, I'm not sure that module
summary section is actually needed; but, it is probably better to address that
when the module is converted to use Argument Clinic.  In the meantime we
should keep the list complete.

Doc/library/gc.rst

@@ -69,9 +69,10 @@ The :mod:`gc` module provides the following functions:
 
 .. function:: get_stats()
 
-   Return a list of 3 per-generation dictionaries containing collection
-   statistics since interpreter start.  At this moment, each dictionary will
-   contain the following items:
+   Return a list of three per-generation dictionaries containing collection
+   statistics since interpreter start.  The number of keys may change
+   in the future, but currently each dictionary will contain the following
+   items:
 
    * ``collections`` is the number of times this generation was collected;
 

Doc/whatsnew/3.4.rst

@@ -628,6 +628,14 @@ multiple implementations of an operation that allows it to work with
       PEP written and implemented by Łukasz Langa.
 
 
+gc
+--
+
+New :func:`~gc.get_stats` returns a list of three per-generation dictionaries
+containing the collections statistics since interpreter startup.  (Contributed
+by Antoine Pitrou in :issue:`16351`.)
+
+
 hashlib
 -------
 

Modules/gcmodule.c

@@ -1498,6 +1498,7 @@ PyDoc_STRVAR(gc__doc__,
 "isenabled() -- Returns true if automatic collection is enabled.\n"
 "collect() -- Do a full collection right now.\n"
 "get_count() -- Return the current collection counts.\n"
+"get_stats() -- Return list of dictionaries containing per-generation stats.\n"
 "set_debug() -- Set debugging flags.\n"
 "get_debug() -- Get debugging flags.\n"
 "set_threshold() -- Set the collection thresholds.\n"