bpo-29554: Improve docs for pstat module and profile. (#88) (#227)

Clarify that methods take a string which is interpreted as a regex,
not a regex object.

Also clarify what the old `-1`, `0`, `1` and `2` options were.

(cherry picked from commit 8fb1f6e)

Author: berkerpeksag

Doc/library/profile.rst

@@ -444,9 +444,10 @@ Analysis of the profiler data is done using the :class:`~pstats.Stats` class.
       significant entries.  Initially, the list is taken to be the complete set
       of profiled functions.  Each restriction is either an integer (to select a
       count of lines), or a decimal fraction between 0.0 and 1.0 inclusive (to
-      select a percentage of lines), or a regular expression (to pattern match
-      the standard name that is printed.  If several restrictions are provided,
-      then they are applied sequentially.  For example::
+      select a percentage of lines), or a string that will interpreted as a
+      regular expression (to pattern match the standard name that is printed).
+      If several restrictions are provided, then they are applied sequentially.
+      For example::
 
          print_stats(.1, 'foo:')
 

Lib/pstats.py

@@ -48,11 +48,14 @@ class Stats:
     printed.
 
     The sort_stats() method now processes some additional options (i.e., in
-    addition to the old -1, 0, 1, or 2).  It takes an arbitrary number of
-    quoted strings to select the sort order.  For example sort_stats('time',
-    'name') sorts on the major key of 'internal function time', and on the
-    minor key of 'the name of the function'.  Look at the two tables in
-    sort_stats() and get_sort_arg_defs(self) for more examples.
+    addition to the old -1, 0, 1, or 2 that are respectively interpreted as
+    'stdname', 'calls', 'time', and 'cumulative').  It takes an arbitrary number
+    of quoted strings to select the sort order.
+
+    For example sort_stats('time', 'name') sorts on the major key of 'internal
+    function time', and on the minor key of 'the name of the function'.  Look at
+    the two tables in sort_stats() and get_sort_arg_defs(self) for more
+    examples.
 
     All methods return self, so you can string together commands like:
         Stats('foo', 'goo').strip_dirs().sort_stats('calls').\