diff --git a/docs/library/framebuf.rst b/docs/library/framebuf.rst
index 78ae0c1c3..149f4d660 100644
--- a/docs/library/framebuf.rst
+++ b/docs/library/framebuf.rst
@@ -133,7 +133,9 @@ Other methods
     Draw another FrameBuffer on top of the current one at the given coordinates.
     If *key* is specified then it should be a color integer and the
     corresponding color will be considered transparent: all pixels with that
-    color value will not be drawn.
+    color value will not be drawn. (If the *palette* is specified then the *key*
+    is compared to the value from *palette*, not to the value directly from
+    *fbuf*.)
 
     The *palette* argument enables blitting between FrameBuffers with differing
     formats. Typical usage is to render a monochrome or grayscale glyph/icon to