More trivial comment -> docstring transformations by Ka-Ping Yee,

who writes:

Here is batch 2, as a big collection of CVS context diffs.
Along with moving comments into docstrings, i've added a
couple of missing docstrings and attempted to make sure more
module docstrings begin with a one-line summary.

I did not add docstrings to the methods in profile.py for
fear of upsetting any careful optimizations there, though
i did move class documentation into class docstrings.

The convention i'm using is to leave credits/version/copyright
type of stuff in # comments, and move the rest of the descriptive
stuff about module usage into module docstrings.  Hope this is
okay.

1 files changed, 45 insertions, 51 deletions

diff --git a/Lib/pstats.py b/Lib/pstats.py
index 25ca7fb..413351d 100644
--- a/Lib/pstats.py
+++ b/Lib/pstats.py
@@ -1,4 +1,5 @@
-#
+"""Class for printing reports on profiled python code."""
+
 # Class for printing reports on profiled python code. rev 1.0  4/1/94
 #
 # Based on prior profile module by Sjoerd Mullender...
@@ -37,41 +38,38 @@ import string
 import marshal
 import re
 
-#**************************************************************************
-# Class Stats documentation
-#**************************************************************************
-# This class is used for creating reports from data generated by the
-# Profile class.  It is a "friend" of that class, and imports data either
-# by direct access to members of Profile class, or by reading in a dictionary
-# that was emitted (via marshal) from the Profile class.
-#
-# The big change from the previous Profiler (in terms of raw functionality)
-# is that an "add()" method has been provided to combine Stats from
-# several distinct profile runs.  Both the constructor and the add()
-# method now take arbitrarilly many file names as arguments.
-#
-# All the print methods now take an argument that indicats how many lines
-# to print.  If the arg is a floating point number between 0 and 1.0, then
-# it is taken as a decimal percentage of the availabel lines to be printed
-# (e.g., .1 means print 10% of all available lines).  If it is an integer,
-# it is taken to mean the number of lines of data that you wish to have
-# printed.
-#
-# The sort_stats() method now processes some additionaly 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.
-#
-# All methods now return "self",  so you can string together commands like:
-#    Stats('foo', 'goo').strip_dirs().sort_stats('calls').\
-#                               print_stats(5).print_callers(5)
-# 
-#**************************************************************************
 import fpformat
 
 class Stats:
+	"""This class is used for creating reports from data generated by the
+	Profile class.  It is a "friend" of that class, and imports data either
+	by direct access to members of Profile class, or by reading in a dictionary
+	that was emitted (via marshal) from the Profile class.
+
+	The big change from the previous Profiler (in terms of raw functionality)
+	is that an "add()" method has been provided to combine Stats from
+	several distinct profile runs.  Both the constructor and the add()
+	method now take arbitrarilly many file names as arguments.
+
+	All the print methods now take an argument that indicats how many lines
+	to print.  If the arg is a floating point number between 0 and 1.0, then
+	it is taken as a decimal percentage of the availabel lines to be printed
+	(e.g., .1 means print 10% of all available lines).  If it is an integer,
+	it is taken to mean the number of lines of data that you wish to have
+	printed.
+
+	The sort_stats() method now processes some additionaly 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.
+
+	All methods now return "self",  so you can string together commands like:
+	    Stats('foo', 'goo').strip_dirs().sort_stats('calls').\
+	                        print_stats(5).print_callers(5)
+	"""
+	
 	def __init__(self, *args):
 		if not len(args):
 			arg = None
@@ -182,8 +180,8 @@ class Stats:
 		  "time"      : (((2,-1),              ), "internal time"),\
 		  }
 
-	# Expand all abbreviations that are unique
 	def get_sort_arg_defs(self):
+		"""Expand all abbreviations that are unique."""
 		if not self.sort_arg_dict:
 			self.sort_arg_dict = dict = {}
 			std_list = dict.keys()
@@ -289,9 +287,9 @@ class Stats:
 				all_callees[func2][func]  = callers[func2]
 		return
 
-        #******************************************************************
+	#******************************************************************
 	# The following functions support actual printing of reports
-        #******************************************************************
+	#******************************************************************
 
 	# Optional "amount" is either a line count, or a percentage of lines.
 
@@ -447,17 +445,14 @@ class Stats:
 		pass # has no return value, so use at end of line :-)
 
 
-#**************************************************************************
-# class TupleComp Documentation
-#**************************************************************************
-# This class provides a generic function for comparing any two tuples.
-# Each instance records a list of tuple-indicies (from most significant
-# to least significant), and sort direction (ascending or decending) for
-# each tuple-index.  The compare functions can then be used as the function
-# argument to the system sort() function when a list of tuples need to be
-# sorted in the instances order.
-#**************************************************************************
 class TupleComp:
+	"""This class provides a generic function for comparing any two tuples.
+	Each instance records a list of tuple-indicies (from most significant
+	to least significant), and sort direction (ascending or decending) for
+	each tuple-index.  The compare functions can then be used as the function
+	argument to the system sort() function when a list of tuples need to be
+	sorted in the instances order."""
+
 	def __init__(self, comp_select_list):
 		self.comp_select_list = comp_select_list
 
@@ -495,16 +490,16 @@ def func_split(func_name):
 # such as callers and callees. 
 #**************************************************************************
 
-    # Add together all the stats for two profile entries
-def add_func_stats(target, source):				
+def add_func_stats(target, source):
+	"""Add together all the stats for two profile entries."""
 	cc, nc, tt, ct, callers = source
 	t_cc, t_nc, t_tt, t_ct, t_callers = target
 	return (cc+t_cc, nc+t_nc, tt+t_tt, ct+t_ct, \
 		  add_callers(t_callers, callers))
 
 
-    # Combine two caller lists in a single list.
 def add_callers(target, source):
+	"""Combine two caller lists in a single list."""
 	new_callers = {}
 	for func in target.keys():
 		new_callers[func] = target[func]
@@ -515,8 +510,8 @@ def add_callers(target, source):
 			new_callers[func] = source[func]
 	return new_callers
 
-     # Sum the caller statistics to get total number of calls recieved
 def count_calls(callers):
+	"""Sum the caller statistics to get total number of calls received."""
 	nc = 0
 	for func in callers.keys():
 		nc = nc + callers[func]
@@ -529,4 +524,3 @@ def count_calls(callers):
 def f8(x):
 	return string.rjust(fpformat.fix(x, 3), 8)
 
-