--- a/src/transform.doc	Sat Aug 02 06:36:32 2008 +0000
+++ b/src/transform.doc	Mon Aug 04 19:26:15 2008 +0000
@@ -146,22 +146,33 @@
 New in pygame 1.8
 <END>
 
+average_color
+finds the average color of a surface
+pygame.transform.average_color(Surface, Rect = None): return Color
 
+Finds the average color of a Surface or a region of a surface specified by a
+Rect, and returns it as a Color.
+<END>
 
 threshold
 finds which, and how many pixels in a surface are within a threshold of a color.
+pygame.transform.threshold(DestSurface, Surface, color, threshold = (0,0,0,0), diff_color = (0,0,0,0), change_return = True, Surface = None, inverse = False): return num_threshold_pixels
 
-pygame.transform.threshold(DestSurface, Surface, color, threshold = (0,0,0,0), diff_color = (0,0,0,0), change_return = True, Surface =None): return num_threshold_pixels
+Finds which, and how many pixels in a surface are within a threshold of a color.
 
 It can set the destination surface where all of the pixels not within the 
-threshold are changed to diff_color.
+threshold are changed to diff_color.  If inverse is optionally set to True, the
+pixels that are within the threshold are instead changed to diff_color.
+
+If the optional second surface is given, it is used to threshold against
+rather than the specified color.  That is, it will find each pixel in the first
+Surface that is within the threshold of the pixel at the same coordinates of
+the second Surface.  If change_return is set, the pixels set in DestSurface will
+be those from the first Surface.
 
 Or it can be used to just count the number of pixels within the threshold if you set
 change_return to False.
 
-When given the optional third surface, it will use the colors in that rather 
-than the 3rd position "color" arg.
-
 You can use a threshold of (r,g,b,a) where the r,g,b can have different thresholds. So
 you could use an r threshold of 40 and a blue threshold of 2 if you like.