diff --git a/src/gui/text/qrawfont.cpp b/src/gui/text/qrawfont.cpp
index 00a2939e79..462c60b1f6 100644
--- a/src/gui/text/qrawfont.cpp
+++ b/src/gui/text/qrawfont.cpp
@@ -579,7 +579,12 @@ bool QRawFont::glyphIndexesForChars(const QChar *chars, int numChars, quint32 *g
    to make it appear as if the two glyphs are unspaced. How the advances are calculated is
    controlled by \a layoutFlags.
 
-   \sa QTextLine::horizontalAdvance(), QFontMetricsF::horizontalAdvance()
+   \note When \c KernedAdvances is requested, this function will apply kerning rules from the
+   TrueType table \c{KERN}, if this is available in the font. In many modern fonts, kerning is
+   handled through OpenType rules or AAT rules, which requires a full shaping step to be applied.
+   To get the results of fully shaping the text, use \l{QTextLayout}.
+
+   \sa QTextLine::horizontalAdvance(), QFontMetricsF::horizontalAdvance(), QTextLayout::glyphRuns()
 */
 
 /*!
@@ -604,7 +609,12 @@ bool QRawFont::glyphIndexesForChars(const QChar *chars, int numChars, quint32 *g
    array \a glyphIndexes while the results are returned through \a advances, both of them must
    have \a numGlyphs elements. How the advances are calculated is controlled by \a layoutFlags.
 
-   \sa QTextLine::horizontalAdvance(), QFontMetricsF::horizontalAdvance()
+   \note When \c KernedAdvances is requested, this function will apply kerning rules from the
+   TrueType table \c{KERN}, if this is available in the font. In many modern fonts, kerning is
+   handled through OpenType rules or AAT rules, which requires a full shaping step to be applied.
+   To get the results of fully shaping the text, use \l{QTextLayout}.
+
+   \sa QTextLine::horizontalAdvance(), QFontMetricsF::horizontalAdvance(), QTextLayout::glyphRuns()
 */
 bool QRawFont::advancesForGlyphIndexes(const quint32 *glyphIndexes, QPointF *advances, int numGlyphs, LayoutFlags layoutFlags) const
 {