doc: Clarify the term advance width

The QFontMetrics documentation has been wrongly stating that the
the horizontalAdvance() gives the width of a string, dating back
to when the function was misnamed as width(). This can cause issues
e.g. when using the value as input to eliding or clipping, since the
advance may be smaller than what is actually drawn.

This tries to clarify the term a bit.

Task-number: QTBUG-90036
Change-Id: I8ed82fa14fe26c2a20cdbee9f2097a0aa4cc3925
Reviewed-by: Lars Knoll <lars@knoll.priv.no>

src/gui/doc/snippets/code/src_gui_text_qfontmetrics.cpp

@@ -9,7 +9,7 @@ void wrapper0() {
 //! [0]
 QFont font("times", 24);
 QFontMetrics fm(font);
-int pixelsWide = fm.horizontalAdvance("What's the width of this text?");
+int pixelsWide = fm.horizontalAdvance("What's the advance width of this text?");
 int pixelsHigh = fm.height();
 //! [0]
 
@@ -22,7 +22,7 @@ void wrapper1() {
 //! [1]
 QFont font("times", 24);
 QFontMetricsF fm(font);
-qreal pixelsWide = fm.horizontalAdvance("What's the width of this text?");
+qreal pixelsWide = fm.horizontalAdvance("What's the advance width of this text?");
 qreal pixelsHigh = fm.height();
 //! [1]
 

src/gui/text/qfontmetrics.cpp

@@ -75,11 +75,19 @@ extern void qt_format_text(const QFont& font, const QRectF &_r,
     inFont(). You can also treat the character as a string, and use
     the string functions on it.
 
-    The string functions include horizontalAdvance(), to return the width of a
-    string in pixels (or points, for a printer), boundingRect(), to
-    return a rectangle large enough to contain the rendered string,
+    The string functions include horizontalAdvance(), to return the advance
+    width of a string in pixels (or points, for a printer), boundingRect(),
+    to return a rectangle large enough to contain the rendered string,
     and size(), to return the size of that rectangle.
 
+    \note The advance width can be different from the width of the actual
+    rendered text. It refers to the distance from the origin of the string to
+    where you would append additional characters. As text may have overhang
+    (in the case of an italic font for instance) or padding between
+    characters, the advance width can be either smaller or larger than the
+    actual rendering of the text. This is called the right bearing of the
+    text.
+
     Example:
     \snippet code/src_gui_text_qfontmetrics.cpp 0