Repository: python-pillow/Pillow

Issue:
Make documentation precise
tl;dr: please use the type you return in documentation. A migration example for deprecated methods wouldn't hurt either

`DeprecationWarning: textsize is deprecated and will be removed in Pillow 10 (2023-07-01). Use textbbox or textlength instead.`

I'm getting a deprecation warning for `ImageDraw.textsize`. Fair enough. I haven't touched this in 7 years but I'll fix it

I'll check the [documentation](https://pillow.readthedocs.io/en/stable/reference/ImageDraw.html)
```
textsize
...
Return the size of the given string, in pixels.
```
But i'm using [0]... (Several prints later) oh, it returns (length_x, length_y)
```
textlength
...
Returns length
```
It says it returns length, but it sure will return length on both axis like the old one. (tries, it only returns length_x)

Okay, i guess i need textbbox instead

```
textbbox (xy, text....)
...
Returns bounding box (in pixels)
xy – The anchor coordinates of the text.
```
Okay, why the hell does it need the coordinates of the text now. How is it relevant? Fine, i don't care, i'll redo the code.. (several tries later)
Okay, what is a bounding box. [Check code](https://pillow.readthedocs.io/en/stable/_modules/PIL/ImageDraw.html#ImageDraw.textbbox). It returns 4 things now?

(Cries a lot...)

(*Sobs*) I only wanted the (length_x, length_y) provided by the old method so i can continue with my life and forgets i have to touch this old code of 7 years

PS: Sorry for the overdramatization. It's a pet peeve of mine with python modules. Not all of them, but they tend to be this imprecise on the documentation compared with other languages and i don't understand why. In python defense, it could be worse (*Looks at perl modules documentation*)


Discussion:

Resolving patch:
diff --git a/src/PIL/ImageFont.py b/src/PIL/ImageFont.py
--- a/src/PIL/ImageFont.py
+++ b/src/PIL/ImageFont.py
@@ -141,6 +141,8 @@ def getsize(self, text, *args, **kwargs):
 
         Use :py:meth:`.getbbox` or :py:meth:`.getlength` instead.
 
+        See :ref:`deprecations <Font size and offset methods>` for more information.
+
         Returns width and height (in pixels) of given text.
 
         :param text: Text to measure.
@@ -432,6 +434,8 @@ def getsize(
         1/64 pixel precision.
         Use :py:meth:`getbbox()` to get the exact bounding box based on an anchor.
 
+        See :ref:`deprecations <Font size and offset methods>` for more information.
+
         Returns width and height (in pixels) of given text if rendered in font with
         provided direction, features, and language.
 
@@ -500,6 +504,8 @@ def getsize_multiline(
 
         Use :py:meth:`.ImageDraw.multiline_textbbox` instead.
 
+        See :ref:`deprecations <Font size and offset methods>` for more information.
+
         Returns width and height (in pixels) of given text if rendered in font
         with provided direction, features, and language, while respecting
         newline characters.
@@ -559,6 +565,8 @@ def getoffset(self, text):
 
         Use :py:meth:`.getbbox` instead.
 
+        See :ref:`deprecations <Font size and offset methods>` for more information.
+
         Returns the offset of given text. This is the gap between the
         starting coordinate and the first marking. Note that this gap is
         included in the result of :py:func:`~PIL.ImageFont.FreeTypeFont.getsize`.
@@ -852,6 +860,8 @@ def getsize(self, text, *args, **kwargs):
         .. deprecated:: 9.2.0
 
         Use :py:meth:`.getbbox` or :py:meth:`.getlength` instead.
+
+        See :ref:`deprecations <Font size and offset methods>` for more information.
         """
         deprecate("getsize", 10, "getbbox or getlength")
         with warnings.catch_warnings():


Test patch: