From d5e1601b32ea43b45ce8f820e4b349e9b5e2dd6c Mon Sep 17 00:00:00 2001
From: Andrew Murray <radarhere@users.noreply.github.com>
Date: Wed, 15 Oct 2025 20:02:12 +1100
Subject: [PATCH] Improved documentation

---
 docs/reference/ImageDraw.rst |  4 ++++
 docs/reference/ImageText.rst | 33 ++++++++++++++++++++++++++++++---
 docs/releasenotes/12.0.0.rst | 33 +++++++++++++++++++++++++++++++++
 3 files changed, 67 insertions(+), 3 deletions(-)

diff --git a/docs/reference/ImageDraw.rst b/docs/reference/ImageDraw.rst
index 6768a04c6..4c9567593 100644
--- a/docs/reference/ImageDraw.rst
+++ b/docs/reference/ImageDraw.rst
@@ -582,6 +582,8 @@ Methods
         hello_world = hello + world  # kerning is disabled, no need to adjust
         assert hello_world == draw.textlength("HelloWorld", font, features=["-kern"])  # True
 
+    .. seealso:: :py:meth:`PIL.ImageText.Text.get_length`
+
     .. versionadded:: 8.0.0
 
     :param text: Text to be measured. May not contain any newline characters.
@@ -683,6 +685,8 @@ Methods
     1/64 pixel precision. The bounding box includes extra margins for
     some fonts, e.g. italics or accents.
 
+    .. seealso:: :py:meth:`PIL.ImageText.Text.get_bbox`
+
     .. versionadded:: 8.0.0
 
     :param xy: The anchor coordinates of the text.
diff --git a/docs/reference/ImageText.rst b/docs/reference/ImageText.rst
index 299561ace..8744ad368 100644
--- a/docs/reference/ImageText.rst
+++ b/docs/reference/ImageText.rst
@@ -4,9 +4,9 @@
 :py:mod:`~PIL.ImageText` module
 ===============================
 
-The :py:mod:`~PIL.ImageText` module defines a class with the same name. Instances of
-this class provide a way to use fonts with text strings or bytes. The result is a
-simple API to apply styling to pieces of text and measure or draw them.
+The :py:mod:`~PIL.ImageText` module defines a :py:class:`~PIL.ImageText.Text` class.
+Instances of this class provide a way to use fonts with text strings or bytes. The
+result is a simple API to apply styling to pieces of text and measure or draw them.
 
 Example
 -------
@@ -27,6 +27,33 @@ Example
     d = ImageDraw.Draw(im)
     d.text((0, 0), text, "#f00")
 
+Comparison
+----------
+
+Without ``ImageText.Text``::
+
+  from PIL import Image, ImageDraw
+  im = Image.new(mode, size)
+  d = ImageDraw.Draw(im)
+
+  d.textlength(text, font, direction, features, language, embedded_color)
+  d.multiline_textbbox(xy, text, font, anchor, spacing, align, direction, features, language, stroke_width, embedded_color)
+  d.text(xy, text, fill, font, anchor, spacing, align, direction, features, language, stroke_width, stroke_fill, embedded_color)
+
+With ``ImageText.Text``::
+
+  from PIL import ImageText
+  text = ImageText.Text(text, font, mode, spacing, direction, features, language)
+  text.embed_color()
+  text.stroke(stroke_width, stroke_fill)
+
+  text.get_length()
+  text.get_bbox(xy, anchor, align)
+
+  im = Image.new(mode, size)
+  d = ImageDraw.Draw(im)
+  d.text(xy, text, fill, anchor=anchor, align=align)
+
 Methods
 -------
 
diff --git a/docs/releasenotes/12.0.0.rst b/docs/releasenotes/12.0.0.rst
index fb5733944..4c00d8c4c 100644
--- a/docs/releasenotes/12.0.0.rst
+++ b/docs/releasenotes/12.0.0.rst
@@ -124,6 +124,39 @@ Image.alpha_composite: LA images
 
 :py:meth:`~PIL.Image.alpha_composite` can now use LA images as well as RGBA.
 
+API additions
+=============
+
+Added ImageText.Text
+^^^^^^^^^^^^^^^^^^^^
+
+:py:class:`PIL.ImageText.Text` has been added, as a simpler way to use fonts with text
+strings or bytes.
+
+Without ``ImageText.Text``::
+
+  from PIL import Image, ImageDraw
+  im = Image.new(mode, size)
+  d = ImageDraw.Draw(im)
+
+  d.textlength(text, font, direction, features, language, embedded_color)
+  d.multiline_textbbox(xy, text, font, anchor, spacing, align, direction, features, language, stroke_width, embedded_color)
+  d.text(xy, text, fill, font, anchor, spacing, align, direction, features, language, stroke_width, stroke_fill, embedded_color)
+
+With ``ImageText.Text``::
+
+  from PIL import ImageText
+  text = ImageText.Text(text, font, mode, spacing, direction, features, language)
+  text.embed_color()
+  text.stroke(stroke_width, stroke_fill)
+
+  text.get_length()
+  text.get_bbox(xy, anchor, align)
+
+  im = Image.new(mode, size)
+  d = ImageDraw.Draw(im)
+  d.text(xy, text, fill, anchor=anchor, align=align)
+
 Other changes
 =============