doc: Fix several text-related qdoc warnings

Also adds a new snippet which is just copy-pasted from the
old documentation, because the snippet-file previously referenced
seems to have disappeared.

Change-Id: I0180715544321e076acda769cbdcbf19d50a971b
Reviewed-by: Casper van Donderen <casper.vandonderen@nokia.com>

10 files changed, 87 insertions, 39 deletions

diff --git a/src/gui/doc/snippets/qtextobject/textobjectinterface.h b/src/gui/doc/snippets/qtextobject/textobjectinterface.h
new file mode 100644
index 0000000000..6936b17d04
--- /dev/null
+++ b/src/gui/doc/snippets/qtextobject/textobjectinterface.h
@@ -0,0 +1,46 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+**     the names of its contributors may be used to endorse or promote
+**     products derived from this software without specific prior written
+**     permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [0]
+class SvgTextObject : public QObject, public QTextObjectInterface
+{
+    Q_OBJECT
+    Q_INTERFACES(QTextObjectInterface)
+//! [0]
diff --git a/src/gui/kernel/qplatformsharedgraphicscache.cpp b/src/gui/kernel/qplatformsharedgraphicscache.cpp
index e38ece3cba..b0e25c4a8d 100644
--- a/src/gui/kernel/qplatformsharedgraphicscache.cpp
+++ b/src/gui/kernel/qplatformsharedgraphicscache.cpp
@@ -73,7 +73,7 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-    \enum BufferType
+    \enum QPlatformSharedGraphicsCache::BufferType
 
     Defines how the type of buffer required to contain a cache.
 
@@ -83,7 +83,7 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-    \enum PixelFormat
+    \enum QPlatformSharedGraphicsCache::PixelFormat
 
     Defines the pixel format of a cache.
 
@@ -93,7 +93,7 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-   \fn void ensureCacheInitialized(const QByteArray &cacheId, BufferType bufferType, PixelFormat pixelFormat)
+   \fn void QPlatformSharedGraphicsCache::ensureCacheInitialized(const QByteArray &cacheId, BufferType bufferType, PixelFormat pixelFormat)
 
    Initializes a cache named \a cacheId if it has not yet been initialized. The \a bufferType and
    \a pixelFormat gives the format of the buffers that will be used to contain the items in the
@@ -142,7 +142,7 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-    \fn void itemsMissing(const QByteArray &cacheId, const QVector<quint32> *itemIds)
+    \fn void QPlatformSharedGraphicsCache::itemsMissing(const QByteArray &cacheId, const QVector<quint32> &itemIds)
 
     This signal is emitted when requestItems() has been called for one or more items in the
     cache named \a cacheId which are not yet available in the cache. The user is then expected to
@@ -155,7 +155,7 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-    \fn void itemsAvailable(const QByteArray &cacheId, void *bufferId, const QSize &bufferSize, const QVector<quint32> &itemIds, const QVector<QPoint> &positionsInBuffer)
+    \fn void QPlatformSharedGraphicsCache::itemsAvailable(const QByteArray &cacheId, void *bufferId, const QVector<quint32> &itemIds, const QVector<QPoint> &positionsInBuffer)
 
     This signal can be emitted at any time when either requestItems() or insertItems() has been
     called by the application for one or more items in the cache named \a cacheId, as long as
@@ -181,7 +181,7 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-    \fn void itemsUpdated(const QByteArray &cacheId, void *bufferId, const QSize &bufferSize, const QVector<quint32> &itemIds, const QVector<QPoint> &positionsInBuffer)
+    \fn void QPlatformSharedGraphicsCache::itemsUpdated(const QByteArray &cacheId, void *bufferId, const QVector<quint32> &itemIds, const QVector<QPoint> &positionsInBuffer)
 
     This signal is similar in usage to the itemsAvailable() signal, but will be emitted when
     the location of a previously requested or inserted item has been updated. The application
@@ -196,7 +196,7 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-    \fn void itemsInvalidated(const QByteArray &cacheId, const QVector<quint32> &itemIds)
+    \fn void QPlatformSharedGraphicsCache::itemsInvalidated(const QByteArray &cacheId, const QVector<quint32> &itemIds)
 
     This signal is emitted when the items given by \a itemIds in the cache named \a cacheId have
     been removed from the cache and the previously reported information about them is considered
@@ -214,7 +214,7 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-    \fn void beginRequestBatch()
+    \fn void QPlatformSharedGraphicsCache::beginRequestBatch()
 
     This is a hint to the cache that a burst of requests is pending. In some implementations, this
     will improve performance, as the cache can focus on handling the requests and wait with the
@@ -232,7 +232,7 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-    \fn void endRequestBatch()
+    \fn void QPlatformSharedGraphicsCache::endRequestBatch()
 
     Signals to the cache that the request sequence which has previously been commenced using
     beginRequestBatch() has now finished.
@@ -241,7 +241,7 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-   \fn bool requestBatchStarted() const
+   \fn bool QPlatformSharedGraphicsCache::requestBatchStarted() const
 
    Returns true if a request batch has previously been started using beginRequestBatch()
    and not yet stopped using endRequestBatch().
@@ -250,7 +250,7 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-    \fn uint textureIdForBuffer(void *bufferId)
+    \fn uint QPlatformSharedGraphicsCache::textureIdForBuffer(void *bufferId)
 
     Returns an OpenGL texture ID corresponding to the buffer \a bufferId, which has previously
     been passed through signals itemsAvailable() or itemsUpdated(). The relevant OpenGL context
@@ -260,7 +260,7 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-    \fn void *eglImageForBuffer(void *bufferId)
+    \fn void *QPlatformSharedGraphicsCache::eglImageForBuffer(void *bufferId)
 
     Returns an EGLImageKHR image corresponding to the buffer \a bufferId.
 
@@ -268,7 +268,7 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-    \fn void referenceBuffer(void *bufferId)
+    \fn void QPlatformSharedGraphicsCache::referenceBuffer(void *bufferId)
 
     Registers a reference to the buffer \a bufferId.
 
@@ -276,7 +276,7 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-    \fn bool dereferenceBuffer(void *bufferId)
+    \fn bool QPlatformSharedGraphicsCache::dereferenceBuffer(void *bufferId)
 
     Removed a previously registered reference to the buffer \a bufferId. Returns true if there
     are still more references to the buffer in question, or false if this was the last reference
@@ -286,7 +286,7 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-    \fn QSize sizeOfBuffer(void *bufferId)
+    \fn QSize QPlatformSharedGraphicsCache::sizeOfBuffer(void *bufferId)
 
     Returns the size of the buffer \a bufferId.
 
diff --git a/src/gui/text/qabstracttextdocumentlayout.cpp b/src/gui/text/qabstracttextdocumentlayout.cpp
index f83539543a..5f0a8ac14f 100644
--- a/src/gui/text/qabstracttextdocumentlayout.cpp
+++ b/src/gui/text/qabstracttextdocumentlayout.cpp
@@ -122,7 +122,7 @@ QT_BEGIN_NAMESPACE
     and QTextObjectInterface. QObject must be the first class
     inherited. For instance:
 
-    \snippet richtext/textobject/svgtextobject.h 1
+    \snippet qtextobject/textobjectinterface.h 0
 
     The data of a text object is usually stored in the QTextCharFormat
     using QTextCharFormat::setProperty(), and then retrieved with
diff --git a/src/gui/text/qfont.cpp b/src/gui/text/qfont.cpp
index 20ba367e26..7f5ed7eda3 100644
--- a/src/gui/text/qfont.cpp
+++ b/src/gui/text/qfont.cpp
@@ -489,7 +489,7 @@ QFontEngineData::~QFontEngineData()
     Information on encodings can be found from
     \l{Roman Czyborra's} page.
 
-    \sa QFontComboBox, QFontMetrics, QFontInfo, QFontDatabase, {Character Map Example}
+    \sa QFontMetrics, QFontInfo, QFontDatabase, {Character Map Example}
 */
 
 /*!
@@ -786,8 +786,8 @@ QString QFont::styleName() const
 /*!
     \since 4.8
 
-    Sets the style name of the font. When set, other style properties
-    like \a style() and \a weight() will be ignored for font matching.
+    Sets the style name of the font to \a styleName. When set, other style properties
+    like \l style() and \l weight() will be ignored for font matching.
 
     \sa styleName()
 */
diff --git a/src/gui/text/qfontdatabase.cpp b/src/gui/text/qfontdatabase.cpp
index 1d4eaa5576..b429fbd910 100644
--- a/src/gui/text/qfontdatabase.cpp
+++ b/src/gui/text/qfontdatabase.cpp
@@ -1203,7 +1203,7 @@ QString QFontDatabase::styleString(const QFontInfo &fontInfo)
     each combination of family and style, displaying this information
     in a tree view.
 
-    \sa QFont, QFontInfo, QFontMetrics, QFontComboBox, {Character Map Example}
+    \sa QFont, QFontInfo, QFontMetrics, {Character Map Example}
 */
 
 /*!
@@ -1526,7 +1526,7 @@ bool  QFontDatabase::isScalable(const QString &family,
 
 /*!
     Returns a list of the point sizes available for the font that has
-    family \a family and style \a style. The list may be empty.
+    family \a family and style \a styleName. The list may be empty.
 
     \sa smoothSizes(), standardSizes()
 */
@@ -1627,7 +1627,7 @@ QFont QFontDatabase::font(const QString &family, const QString &style,
 
 /*!
     Returns the point sizes of a font that has family \a family and
-    style \a style that will look attractive. The list may be empty.
+    style \a styleName that will look attractive. The list may be empty.
     For non-scalable fonts and bitmap scalable fonts, this function
     is equivalent to pointSizes().
 
diff --git a/src/gui/text/qfontmetrics.cpp b/src/gui/text/qfontmetrics.cpp
index 488bb68ec4..5fd31dbfdf 100644
--- a/src/gui/text/qfontmetrics.cpp
+++ b/src/gui/text/qfontmetrics.cpp
@@ -125,7 +125,7 @@ extern void qt_format_text(const QFont& font, const QRectF &_r,
     Example:
     \snippet code/src_gui_text_qfontmetrics.cpp 0
 
-    \sa QFont, QFontInfo, QFontDatabase, QFontComboBox, {Character Map Example}
+    \sa QFont, QFontInfo, QFontDatabase, {Character Map Example}
 */
 
 /*!
@@ -412,7 +412,7 @@ bool QFontMetrics::inFont(QChar ch) const
 }
 
 /*!
-   Returns true if the character encoded in UCS-4/UTF-32 is a valid
+   Returns true if the character \a ucs4 encoded in UCS-4/UTF-32 is a valid
    character in the font; otherwise returns false.
 */
 bool QFontMetrics::inFontUcs4(uint ucs4) const
diff --git a/src/gui/text/qsyntaxhighlighter.cpp b/src/gui/text/qsyntaxhighlighter.cpp
index fb02ad6686..608a1ceca1 100644
--- a/src/gui/text/qsyntaxhighlighter.cpp
+++ b/src/gui/text/qsyntaxhighlighter.cpp
@@ -241,17 +241,16 @@ void QSyntaxHighlighterPrivate::reformatBlock(const QTextBlock &block)
     \ingroup richtext-processing
 
     The QSyntaxHighlighter class is a base class for implementing
-    QTextEdit syntax highlighters.  A syntax highligher automatically
-    highlights parts of the text in a QTextEdit, or more generally in
-    a QTextDocument. Syntax highlighters are often used when the user
-    is entering text in a specific format (for example source code)
+    QTextDocument syntax highlighters.  A syntax highligher automatically
+    highlights parts of the text in a QTextDocument. Syntax highlighters are
+    often used when the user is entering text in a specific format (for example source code)
     and help the user to read the text and identify syntax errors.
 
     To provide your own syntax highlighting, you must subclass
     QSyntaxHighlighter and reimplement highlightBlock().
 
     When you create an instance of your QSyntaxHighlighter subclass,
-    pass it the QTextEdit or QTextDocument that you want the syntax
+    pass it the QTextDocument that you want the syntax
     highlighting to be applied to. For example:
 
     \snippet code/src_gui_text_qsyntaxhighlighter.cpp 0
@@ -306,7 +305,7 @@ void QSyntaxHighlighterPrivate::reformatBlock(const QTextBlock &block)
     parsing the paragraph's text. For an example, see the
     setCurrentBlockUserData() documentation.
 
-    \sa QTextEdit, {Syntax Highlighter Example}
+    \sa QTextDocument, {Syntax Highlighter Example}
 */
 
 /*!
diff --git a/src/gui/text/qtextdocument.cpp b/src/gui/text/qtextdocument.cpp
index 181c013420..3203f85cc9 100644
--- a/src/gui/text/qtextdocument.cpp
+++ b/src/gui/text/qtextdocument.cpp
@@ -219,8 +219,7 @@ QTextCodec *Qt::codecForHtml(const QByteArray &ba)
     \reentrant
     \inmodule QtGui
 
-    \brief The QTextDocument class holds formatted text that can be
-    viewed and edited using a QTextEdit.
+    \brief The QTextDocument class holds formatted text.
 
     \ingroup richtext-processing
 
@@ -962,9 +961,9 @@ QString QTextDocument::defaultStyleSheet() const
 
     This signal is emitted whenever the position of a cursor changed
     due to an editing operation. The cursor that changed is passed in
-    \a cursor.  If you need a signal when the cursor is moved with the
-    arrow keys you can use the \l{QTextEdit::}{cursorPositionChanged()} signal in
-    QTextEdit.
+    \a cursor.  If the document is used with the QTextEdit class and you need a signal when the
+    cursor is moved with the arrow keys you can use the \l{QTextEdit::}{cursorPositionChanged()}
+    signal in QTextEdit.
 */
 
 /*!
@@ -1662,7 +1661,7 @@ static void printPage(int index, QPainter *painter, const QTextDocument *doc, co
 }
 
 /*!
-    Prints the document to the given \a device. The QPageablePaintDevice must be
+    Prints the document to the given \a printer. The QPageablePaintDevice must be
     set up before being used with this function.
 
     This is only a convenience method to print the whole document to the printer.
diff --git a/src/gui/text/qtextobject.cpp b/src/gui/text/qtextobject.cpp
index a7cd76c51b..37cefc0947 100644
--- a/src/gui/text/qtextobject.cpp
+++ b/src/gui/text/qtextobject.cpp
@@ -1669,8 +1669,12 @@ QTextBlock::iterator &QTextBlock::iterator::operator--()
 */
 
 /*!
-    Returns the glyphs of this text fragment. The positions of the glyphs are
-    relative to the position of the QTextBlock's layout.
+    Returns the glyphs corresponding to \a len characters of this text fragment starting at
+    position \a pos. The positions of the glyphs are relative to the position of the QTextBlock's
+    layout.
+
+    If \a pos is less than zero, it will default to the start of the QTextFragment. If \a len
+    is less than zero, it will default to the length of the fragment.
 
     \sa QGlyphRun, QTextBlock::layout(), QTextLayout::position(), QPainter::drawGlyphRun()
 */
diff --git a/src/gui/text/qtextoption.cpp b/src/gui/text/qtextoption.cpp
index 377e33efd7..6b002331ea 100644
--- a/src/gui/text/qtextoption.cpp
+++ b/src/gui/text/qtextoption.cpp
@@ -418,7 +418,7 @@ QList<QTextOption::Tab> QTextOption::tabs() const
 */
 
 /*!
-  \fn void setTabs(QList<Tab> tabStops)
+  \fn void setTabs(const QList<Tab> &tabStops)
   Set the Tab properties to \a tabStops.
 
   \sa tabStop(), tabs()