Clarify px_bounds, glyph_bounds docs

glyph/CHANGELOG.md

@@ -1,5 +1,7 @@
 # Unreleased
 * Update _ttf-parser_ to `0.24`.
+* Clarify `OutlinedGlyph::px_bounds`, `Font::glyph_bounds` documentation, 
+  describe how they relates to drawing and each other.
 
 # 0.2.27
 * Add `Font` glyph layout concept documentation demonstrating "ascent", "descent", "h_side_bearing", 

glyph/src/font.rs

@@ -211,10 +211,14 @@ pub trait Font {
         None // Avoid breaking external Font impls.
     }
 
-    /// Returns the layout bounds of this glyph. These are different to the outline `px_bounds()`.
+    /// Returns the layout bounds of this glyph.
     ///
     /// Horizontally: Glyph position +/- h_advance/h_side_bearing.
     /// Vertically: Glyph position +/- ascent/descent.
+    ///
+    /// These are *not* the same as [`OutlinedGlyph::px_bounds`]. If you are drawing pixels
+    /// you should use `px_bounds` and not this method as outlines are not bound by layout
+    /// values.
     #[inline]
     fn glyph_bounds(&self, glyph: &Glyph) -> Rect
     where

glyph/src/outlined.rs

@@ -15,6 +15,8 @@ pub struct Outline {
 
 impl Outline {
     /// Convert unscaled bounds into pixel bounds at a given scale & position.
+    ///
+    /// See [`OutlinedGlyph::px_bounds`].
     pub fn px_bounds(&self, scale_factor: PxScaleFactor, position: Point) -> Rect {
         let Rect { min, max } = self.bounds;
 
@@ -76,7 +78,20 @@ impl OutlinedGlyph {
         self.px_bounds()
     }
 
-    /// Conservative whole number pixel bounding box for this glyph.
+    /// Conservative whole number pixel bounding box for this glyph outline.
+    /// The returned rect is exactly large enough to [`Self::draw`] into.
+    ///
+    /// The rect holds bounding coordinates in the same coordinate space as the [`Glyph::position`].
+    ///
+    /// Note: These bounds depend on the glyph outline. That outline is *not* necessarily bound
+    ///       by the layout/`glyph_bounds()` bounds.
+    /// * The min.x bound may be greater or smaller than the [`Glyph::position`] x.
+    ///   E.g. if a glyph at position x=0 has an outline going off to the left a bit, min.x will be negative.
+    /// * The max.x bound may be greater/smaller than the `position.x + h_advance`.
+    /// * The min.y bound may be greater/smaller than the `position.y - ascent`.
+    /// * The max.y bound may be greater/smaller than the `position.y - descent`.
+    ///
+    /// Pixel bounds coordinates should not be used for layout logic.
     #[inline]
     pub fn px_bounds(&self) -> Rect {
         self.px_bounds

glyph/src/scale.rs

@@ -188,11 +188,15 @@ pub trait ScaleFont<F: Font> {
         self.h_scale_factor() * self.font().kern_unscaled(first, second)
     }
 
-    /// Returns the layout bounds of this glyph. These are different to the outline `px_bounds()`.
+    /// Returns the layout bounds of this glyph.
     ///
     /// Horizontally: Glyph position +/- h_advance/h_side_bearing.
     /// Vertically: Glyph position +/- ascent/descent.
     ///
+    /// These are *not* the same as [`OutlinedGlyph::px_bounds`]. If you are drawing pixels
+    /// you should use `px_bounds` and not this method as outlines are not bound by layout
+    /// values.
+    ///
     /// Note this method does not make use of the associated scale, as `Glyph`
     /// already includes one of it's own.
     #[inline]