doc: Update documentation for QStaticText

Make some smaller modifications, fixes and additions. Remove \internal
because the API is public now, and add documentation for
QPainter::drawStaticText() since this was missing.

Reviewed-by: TrustMe

2 files changed, 39 insertions, 12 deletions

diff --git a/src/gui/painting/qpainter.cpp b/src/gui/painting/qpainter.cpp
index e26a24d..2cb6915 100644
--- a/src/gui/painting/qpainter.cpp
+++ b/src/gui/painting/qpainter.cpp
@@ -5702,12 +5702,16 @@ void QPainter::drawImage(const QRectF &targetRect, const QImage &image, const QR
 
     \fn void QPainter::drawStaticText(const QPoint &position, const QStaticText &staticText)
 
+    \since 4.7
+
     \overload
 */
 
 /*!
     \fn void QPainter::drawStaticText(int x, int y, const QStaticText &staticText)
 
+    \since 4.7
+
     \overload
 */
 
@@ -5733,6 +5737,25 @@ void QPainter::drawText(const QPointF &p, const QString &str)
     drawText(p, str, 0, 0);
 }
 
+/*!
+    \since 4.7
+
+    Draws the given \a staticText at the given \a position.
+
+    The text will be drawn using the font and the transformation set on the painter. If the
+    font and/or transformation set on the painter are different from the ones used to initialize
+    the layout of the QStaticText, then the layout will have to be recalculated. Use
+    QStaticText::prepare() to initialize \a staticText with the font and transformation with which
+    it will later be drawn.
+
+    If \a position is not the same as when \a staticText was initialized, or when it was last drawn,
+    then there will be a slight overhead when translating the text to its new position.
+
+    \note If the painter's transformation is not affine, then \a staticText will be drawn using regular
+    calls to drawText(), losing any potential performance improvement.
+
+    \sa QStaticText
+*/
 void QPainter::drawStaticText(const QPointF &position, const QStaticText &staticText)
 {
     Q_D(QPainter);
diff --git a/src/gui/text/qstatictext.cpp b/src/gui/text/qstatictext.cpp
index 6cf7022..e3f1d26 100644
--- a/src/gui/text/qstatictext.cpp
+++ b/src/gui/text/qstatictext.cpp
@@ -50,7 +50,6 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \class QStaticText
-    \internal
     \brief The QStaticText class enables optimized drawing of text when the text and its layout
     is updated rarely.
     \since 4.7
@@ -63,11 +62,13 @@ QT_BEGIN_NAMESPACE
     more efficiently than by using QPainter::drawText() in which the layout information is 
     recalculated with every call. 
 
-    The class primarily provides an optimization for cases where text and the transformations on
-    the painter are static over several paint events. If the text or its layout is changed
-    regularly, QPainter::drawText() is the more efficient alternative. Translating the painter
-    will not cause the layout of the text to be recalculated, but will cause a very small
-    performance impact on drawStaticText(). Altering any other parts of the painter's
+    The class primarily provides an optimization for cases where the text, its font and the
+    transformations on the painter are static over several paint events. If the text or its layout
+    is changed for every iteration, QPainter::drawText() is the more efficient alternative, since
+    the static text's layout would have to be recalculated to take the new state into consideration.
+
+    Translating the painter will not cause the layout of the text to be recalculated, but will cause
+    a very small performance impact on drawStaticText(). Altering any other parts of the painter's
     transformation or the painter's font will cause the layout of the static text to be
     recalculated. This should be avoided as often as possible to maximize the performance
     benefit of using QStaticText.
@@ -107,6 +108,11 @@ QT_BEGIN_NAMESPACE
     passed to QPainter::drawStaticText() and can change from call to call with a minimal impact
     on performance.
 
+    QStaticText will attempt to guess the format of the input text using Qt::mightBeRichText().
+    To force QStaticText to display its contents as either plain text or rich text, use the
+    function QStaticText::setTextFormat() and pass in, respectively, Qt::PlainText and
+    Qt::RichText.
+
     \sa QPainter::drawText(), QPainter::drawStaticText(), QTextLayout, QTextDocument
 */
 
@@ -119,11 +125,9 @@ QStaticText::QStaticText()
 }
 
 /*!
-    \fn QStaticText::QStaticText(const QString &text, const QFont &font, const QSizeF &maximumSize)
+    Constructs a QStaticText object with the given \a text and bounded by the given \a size.
 
-    Constructs a QStaticText object with the given \a text which is to be rendered in the given
-    \a font and bounded by the given \a maximumSize. If an invalid size is passed for \a maximumSize
-    the text will be unbounded.         
+    If an invalid size is passed for \a size the text will be unbounded.
 */
 QStaticText::QStaticText(const QString &text, const QSizeF &size)
     : data(new QStaticTextPrivate)
@@ -302,11 +306,11 @@ bool QStaticText::useBackendOptimizations() const
 }
 
 /*!
-    Sets the maximum size of the QStaticText to \a maximumSize.
+    Sets the maximum size of the QStaticText to \a size.
 
     \note This function will cause the layout of the text to be recalculated.
 
-    \sa maximumSize()
+    \sa maximumSize(), size()
 */
 void QStaticText::setMaximumSize(const QSizeF &size)
 {