From f7bc6b4c45c1544a6b892ed5bf7c14255d0e56ca Mon Sep 17 00:00:00 2001
From: Nicolas Silva <nical@fastmail.com>
Date: Sun, 31 Dec 2017 19:30:33 +0100
Subject: [PATCH] Better document Rect::from_points.

---
 src/rect.rs | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/src/rect.rs b/src/rect.rs
index b66fa318..b9b491a6 100644
--- a/src/rect.rs
+++ b/src/rect.rs
@@ -220,8 +220,19 @@ where T: Copy + Clone + Zero + PartialOrd + PartialEq + Add<T, Output=T> + Sub<T
         self.translate(&size.to_vector())
     }
 
-    /// Returns the smallest rectangle containing the four points.
+    /// Returns the smallest rectangle defined by the top/bottom/left/right-most
+    /// points provided as parameter.
+    ///
+    /// Note: This function has a behavior that can be surprising because
+    /// the right-most and bottom-most points are exactly on the edge
+    /// of the rectangle while the `contains` function is has exclusive
+    /// semantic on these edges. This means that the right-most and bottom-most
+    /// points provided to `from_points` will count as not contained by the rect.
+    /// This behavior may change in the future.
     pub fn from_points(points: &[TypedPoint2D<T, U>]) -> Self {
+        // TODO: it would be less confusing if we inflated the size by the smallest
+        // possible value for the given scalar type to avoid the confusion described
+        // above.
         if points.is_empty() {
             return TypedRect::zero();
         }