[cairo] Cairo documentation for stroke_extents is misleading about top left bottom right and distances.

[bootch at nc.rr.com]

Cairo documentation for stroke_extents is misleading about top left bottom right and distances. The pycairo documentation for stroke_extents() says: 
 
x1: left of the resulting extents 
y1: top of the resulting extents 
x2: right ... 
y2: bottom... 
 
Using the word left and right implies that x1 is less than x2.  However, that assertion is not true. 
 
Better if the documentation (in several places) says: 
 
x1: x of the first point 
... 
where x1, y1 and x2, y2 are two points that define some diagonal of the bounding box. 
 
In other words, x2 minus x1 is not a proper formula for the width (a distance) of the stroke extents, since it can be negative.  

Some models, such as gdk.Rectangle, don't properly allow a negative distance.  A common use of extents is to get a gdk.Rectangle for use in invalidate().  To compute a gdk.Rectangle from stroke extents requires (Python):

x1, y1 = context.user_to_device(x1, y1)
x2, y2 = context.user_to_device(x2, y2)
width = abs(x2 - x1)
height = abs(y2 - y1)
x = min(x1, x2)
y = min(y1, y2)
# expand float rect to outside integral pixel
self.value = gdk.Rectangle(int(x), int(y), int(math.ceil(width)), int(math.ceil(height)))

A neive Cairo user (myself) might just use: width = x2 - x1

Thanks.