Doc: Fixed qdoc warnings.

19 files changed, 120 insertions, 90 deletions

diff --git a/src/corelib/io/qfile.cpp b/src/corelib/io/qfile.cpp
index 929b2f9..06c403a 100644
--- a/src/corelib/io/qfile.cpp
+++ b/src/corelib/io/qfile.cpp
@@ -366,9 +366,11 @@ QFilePrivate::setError(QFile::FileError err, int errNum)
 
     \value AutoCloseHandle The file handle passed into open() should be
     closed by close(), the default behaviour is that close just flushes
-    the file and the app is responsible for closing the file handle. When
-    opening a file by name, this flag is ignored as Qt always "owns" the
+    the file and the application is responsible for closing the file handle.
+    When opening a file by name, this flag is ignored as Qt always "owns" the
     file handle and must close it.
+    \value DontCloseHandle The file handle passed into open() will not be
+    closed by Qt. The application must ensure that close() is called.
  */
 
 #ifdef QT3_SUPPORT
@@ -1210,7 +1212,7 @@ bool QFile::open(int fd, OpenMode mode)
     Returns true if successful; otherwise returns false.
 
     When a QFile is opened using this function, behaviour of close() is
-    controlled by the AutoCloseHandle flag.
+    controlled by the \a handleFlags argument.
     If AutoCloseHandle is specified, and this function succeeds,
     then calling close() closes the adopted handle.
     Otherwise, close() does not actually close the file, but only flushes it.
@@ -1269,7 +1271,7 @@ bool QFile::open(int fd, OpenMode mode, FileHandleFlags handleFlags)
     Returns true if successful; otherwise returns false.
 
     When a QFile is opened using this function, behaviour of close() is
-    controlled by the AutoCloseHandle flag.
+    controlled by the \a handleFlags argument.
     If AutoCloseHandle is specified, and this function succeeds,
     then calling close() closes the adopted handle.
     Otherwise, close() does not actually close the file, but only flushes it.
diff --git a/src/corelib/io/qfsfileengine.cpp b/src/corelib/io/qfsfileengine.cpp
index 548f9cf..e1f3123 100644
--- a/src/corelib/io/qfsfileengine.cpp
+++ b/src/corelib/io/qfsfileengine.cpp
@@ -233,6 +233,14 @@ bool QFSFileEngine::open(QIODevice::OpenMode openMode, FILE *fh)
     return open(openMode, fh, QFile::DontCloseHandle);
 }
 
+/*!
+    Opens the file handle \a fh in \a openMode mode. Returns true
+    on success; otherwise returns false.
+
+    The \a handleFlags argument specifies whether the file handle will be
+    closed by Qt. See the QFile::FileHandleFlags documentation for more
+    information.
+*/
 bool QFSFileEngine::open(QIODevice::OpenMode openMode, FILE *fh, QFile::FileHandleFlags handleFlags)
 {
     Q_D(QFSFileEngine);
@@ -294,6 +302,14 @@ bool QFSFileEngine::open(QIODevice::OpenMode openMode, int fd)
     return open(openMode, fd, QFile::DontCloseHandle);
 }
 
+/*!
+    Opens the file descriptor \a fd in \a openMode mode. Returns true
+    on success; otherwise returns false.
+
+    The \a handleFlags argument specifies whether the file handle will be
+    closed by Qt. See the QFile::FileHandleFlags documentation for more
+    information.
+*/
 bool QFSFileEngine::open(QIODevice::OpenMode openMode, int fd, QFile::FileHandleFlags handleFlags)
 {
     Q_D(QFSFileEngine);
diff --git a/src/corelib/io/qfsfileengine_unix.cpp b/src/corelib/io/qfsfileengine_unix.cpp
index 9de282a..4961722 100644
--- a/src/corelib/io/qfsfileengine_unix.cpp
+++ b/src/corelib/io/qfsfileengine_unix.cpp
@@ -252,6 +252,14 @@ bool QFSFileEnginePrivate::nativeOpen(QIODevice::OpenMode openMode)
     return true;
 }
 
+/*!
+    Opens the file descriptor specified by \a file in the mode given by
+    \a openMode. Returns true on success; otherwise returns false.
+
+    The \a handleFlags argument specifies whether the file handle will be
+    closed by Qt. See the QFile::FileHandleFlags documentation for more
+    information.
+*/
 bool QFSFileEngine::open(QIODevice::OpenMode openMode, const RFile &file, QFile::FileHandleFlags handleFlags)
 {
     Q_D(QFSFileEngine);
diff --git a/src/corelib/plugin/quuid.cpp b/src/corelib/plugin/quuid.cpp
index eb29e6e..af63b79 100644
--- a/src/corelib/plugin/quuid.cpp
+++ b/src/corelib/plugin/quuid.cpp
@@ -387,17 +387,17 @@ QUuid::QUuid(const QByteArray &text)
 #endif
 
 /*!
-  Creates a QUuid object from the binary representation of the UUID, as
-  specified by RFC 4122 section 4.1.2. See toRfc4122() for a further
-  explanation of the order of bytes required.
+  \since 4.8
 
-  The byte array accepted is NOT a human readable format.
+  Creates a QUuid object from the binary representation of the UUID given
+  by \a bytes, as specified by RFC 4122 section 4.1.2. See toRfc4122() for a
+  further explanation of the order of bytes required.
 
-  If the conversion fails, a null UUID is created.
+  The byte array accepted is \e not a human readable format.
 
-    \since 4.8
+  If the conversion fails, a null UUID is created.
 
-    \sa toRfc4122(), QUuid()
+  \sa toRfc4122(), QUuid()
 */
 QUuid QUuid::fromRfc4122(const QByteArray &bytes)
 {
diff --git a/src/corelib/tools/qlocale.qdoc b/src/corelib/tools/qlocale.qdoc
index 5d4f305..95a7165 100644
--- a/src/corelib/tools/qlocale.qdoc
+++ b/src/corelib/tools/qlocale.qdoc
@@ -806,6 +806,10 @@
     \internal
 */
 /*!
+    \fn QSystemLocale::CurrencyToStringArgument::CurrencyToStringArgument(const QVariant &v, const QString &s)
+    \internal
+*/
+/*!
     \variable QSystemLocale::CurrencyToStringArgument::value
 
     An input value that should be converted to its string representation.
diff --git a/src/gui/embedded/qscreen_qws.cpp b/src/gui/embedded/qscreen_qws.cpp
index 2c10357..b17ade0 100644
--- a/src/gui/embedded/qscreen_qws.cpp
+++ b/src/gui/embedded/qscreen_qws.cpp
@@ -1545,6 +1545,7 @@ QImage::Format QScreenPrivate::preferredImageFormat() const
     \value SvgalibClass QSvgalibScreen
     \value ProxyClass QProxyScreen
     \value GLClass QGLScreen
+    \value IntfbClass QIntfbScreen
     \value CustomClass Unknown QScreen subclass
 
     \sa classId()
diff --git a/src/gui/painting/qpainter.cpp b/src/gui/painting/qpainter.cpp
index 8e64f3b..efb016e 100644
--- a/src/gui/painting/qpainter.cpp
+++ b/src/gui/painting/qpainter.cpp
@@ -5792,16 +5792,19 @@ void QPainter::drawImage(const QRectF &targetRect, const QImage &image, const QR
     d->engine->drawImage(QRectF(x, y, w, h), image, QRectF(sx, sy, sw, sh), flags);
 }
 
+#if !defined(QT_NO_RAWFONT)
 /*!
-    Draws the glyphs represented by \a glyphs at \a position. The \a position gives the
-    edge of the baseline for the string of glyphs. The glyphs will be retrieved from the font
-    selected on \a glyphs and at offsets given by the positions in \a glyphs.
+    \fn void QPainter::drawGlyphRun(const QPointF &position, const QGlyphRun &glyphs)
+
+    Draws the specified \a glyphs at the given \a position.
+    The \a position gives the edge of the baseline for the string of glyphs.
+    The glyphs will be retrieved from the font selected by \a glyphs and at
+    offsets given by the positions in \a glyphs.
 
     \since 4.8
 
     \sa QGlyphRun::setRawFont(), QGlyphRun::setPositions(), QGlyphRun::setGlyphIndexes()
 */
-#if !defined(QT_NO_RAWFONT)
 void QPainter::drawGlyphRun(const QPointF &position, const QGlyphRun &glyphRun)
 {
     Q_D(QPainter);
@@ -9251,9 +9254,9 @@ void QPainter::drawPixmapFragments(const PixmapFragment *fragments, int fragment
     \since 4.8
 
     This function is used to draw the same \a pixmap with multiple target
-    and source rectangles. If \a sourceRects is 0, the whole pixmap will be
-    rendered at each of the target rectangles. The \a hints parameter can be
-    used to pass in drawing hints.
+    and source rectangles specified by \a targetRects. If \a sourceRects is 0,
+    the whole pixmap will be rendered at each of the target rectangles.
+    The \a hints parameter can be used to pass in drawing hints.
 
     This function is potentially faster than multiple calls to drawPixmap(),
     since the backend can optimize state changes.
diff --git a/src/gui/text/qfont.cpp b/src/gui/text/qfont.cpp
index 2d6af3b..2df88e2 100644
--- a/src/gui/text/qfont.cpp
+++ b/src/gui/text/qfont.cpp
@@ -919,8 +919,9 @@ 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 the given \a styleName.
+    When set, other style properties like style() and weight() will be ignored
+    for font matching.
 
     \sa styleName()
 */
diff --git a/src/gui/text/qfontdatabase.cpp b/src/gui/text/qfontdatabase.cpp
index 79503f9..1d463c4 100644
--- a/src/gui/text/qfontdatabase.cpp
+++ b/src/gui/text/qfontdatabase.cpp
@@ -1943,8 +1943,9 @@ 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.
+    \fn QList<int> QFontDatabase::pointSizes(const QString &family, const QString &style)
+    Returns a list of the point sizes available for the font with the
+    given \a family and \a style. The list may be empty.
 
     \sa smoothSizes(), standardSizes()
 */
@@ -2052,8 +2053,9 @@ 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.
+    \fn QList<int> QFontDatabase::smoothSizes(const QString &family, const QString &style)
+    Returns the point sizes of a font with the given \a family and \a style
+    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 f3d4107..1d93d54 100644
--- a/src/gui/text/qfontmetrics.cpp
+++ b/src/gui/text/qfontmetrics.cpp
@@ -442,9 +442,10 @@ bool QFontMetrics::inFont(QChar ch) const
 }
 
 /*!
+   \fn bool QFontMetrics::inFontUcs4(uint character) const
    \since 4.8
 
-   Returns true if the character encoded in UCS-4/UTF-32 is a valid
+   Returns true if the given \a character 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/qglyphrun.cpp b/src/gui/text/qglyphrun.cpp
index 2865d91..442f7cc 100644
--- a/src/gui/text/qglyphrun.cpp
+++ b/src/gui/text/qglyphrun.cpp
@@ -175,7 +175,8 @@ QRawFont QGlyphRun::rawFont() const
 }
 
 /*!
-    Sets the font in which to look up the glyph indexes to \a font.
+    Sets the font specified by \a rawFont to be the font used to look up the
+    glyph indexes.
 
     \sa rawFont(), setGlyphIndexes()
 */
diff --git a/src/gui/text/qplatformfontdatabase_qpa.cpp b/src/gui/text/qplatformfontdatabase_qpa.cpp
index d1d1f94..e3eeca5 100644
--- a/src/gui/text/qplatformfontdatabase_qpa.cpp
+++ b/src/gui/text/qplatformfontdatabase_qpa.cpp
@@ -160,6 +160,9 @@ QSupportedWritingSystems::QSupportedWritingSystems(const QSupportedWritingSystem
     d->ref.ref();
 }
 
+/*!
+    Assigns the \a other supported writing systems object to this object.
+*/
 QSupportedWritingSystems &QSupportedWritingSystems::operator=(const QSupportedWritingSystems &other)
 {
     if (d != other.d) {
@@ -171,6 +174,9 @@ QSupportedWritingSystems &QSupportedWritingSystems::operator=(const QSupportedWr
     return *this;
 }
 
+/*!
+    Destroys the object.
+*/
 QSupportedWritingSystems::~QSupportedWritingSystems()
 {
     if (!d->ref.deref())
@@ -187,12 +193,26 @@ void QSupportedWritingSystems::detach()
     }
 }
 
+/*!
+    Sets the supported state of the writing system given by \a writingSystem to
+    the value specified by \a support. A value of true indicates that the
+    writing system is supported; a value of false indicates that it is
+    unsupported.
+
+    \sa supported()
+*/
 void QSupportedWritingSystems::setSupported(QFontDatabase::WritingSystem writingSystem, bool support)
 {
     detach();
     d->vector[writingSystem] = support;
 }
 
+/*!
+    Returns true if the writing system given by \a writingSystem is supported;
+    otherwise returns false.
+
+    \sa setSupported()
+*/
 bool QSupportedWritingSystems::supported(QFontDatabase::WritingSystem writingSystem) const
 {
     return d->vector.at(writingSystem);
@@ -295,7 +315,7 @@ QStringList QPlatformFontDatabase::addApplicationFont(const QByteArray &fontData
 }
 
 /*!
-
+    Releases the font handle and deletes any associated data loaded from a file.
 */
 void QPlatformFontDatabase::releaseHandle(void *handle)
 {
@@ -304,7 +324,13 @@ void QPlatformFontDatabase::releaseHandle(void *handle)
 }
 
 /*!
+    Returns the path to the font directory.
+
+    The font directory is stored in the general Qt settings unless it has been
+    overridden by the \c QT_QPA_FONTDIR environment variable.
 
+    When using builds of Qt that do not support settings, the \c QT_QPA_FONTDIR
+    environment variable is the only way to specify the font directory.
 */
 QString QPlatformFontDatabase::fontDir() const
 {
diff --git a/src/gui/text/qrawfont.cpp b/src/gui/text/qrawfont.cpp
index e3e5c57..60a6cb3 100644
--- a/src/gui/text/qrawfont.cpp
+++ b/src/gui/text/qrawfont.cpp
@@ -485,7 +485,8 @@ QVector<quint32> QRawFont::glyphIndexesForString(const QString &text) const
    must be at least \a numChars, if that's still not enough, this function will return
    false, then you can resize \a glyphIndexes from the size returned in \a numGlyphs.
 
-   \sa glyphIndexesForString(), advancesForGlyphIndexes(), QGlyphs, QTextLayout::glyphs(), QTextFragment::glyphs()
+   \sa glyphIndexesForString(), advancesForGlyphIndexes(), QGlyphRun,
+       QTextLayout::glyphRuns(), QTextFragment::glyphRuns()
 */
 bool QRawFont::glyphIndexesForChars(const QChar *chars, int numChars, quint32 *glyphIndexes, int *numGlyphs) const
 {
diff --git a/src/imports/shaders/shadereffectitem.cpp b/src/imports/shaders/shadereffectitem.cpp
index 056581c..ca5c9a3 100644
--- a/src/imports/shaders/shadereffectitem.cpp
+++ b/src/imports/shaders/shadereffectitem.cpp
@@ -243,11 +243,6 @@ ShaderEffectItem::~ShaderEffectItem()
 
 */
 
-/*!
-    \property ShaderEffectItem::fragmentShader
-    \brief the OpenGL fragment shader code.
-*/
-
 void ShaderEffectItem::setFragmentShader(const QString &code)
 {
     if (m_fragment_code.constData() == code.constData())
@@ -281,11 +276,6 @@ void ShaderEffectItem::setFragmentShader(const QString &code)
 
 */
 
-/*!
-    \property ShaderEffectItem::vertexShader
-    \brief the OpenGL vertex shader code.
-*/
-
 void ShaderEffectItem::setVertexShader(const QString &code)
 {
     if (m_vertex_code.constData() == code.constData())
@@ -320,11 +310,6 @@ void ShaderEffectItem::setVertexShader(const QString &code)
     The default value is true.
 */
 
-/*!
-    \property ShaderEffectItem::blending
-    \brief the drawing is done using blending.
-*/
-
 void ShaderEffectItem::setBlending(bool enable)
 {
     if (m_blending == enable)
@@ -347,11 +332,6 @@ void ShaderEffectItem::setBlending(bool enable)
     The default value is QSize(1,1).
 */
 
-/*!
-    \property ShaderEffectItem::meshResolution
-    \brief the amount of triangles in the mesh for both x and y-axis.
-*/
-
 void ShaderEffectItem::setMeshResolution(const QSize &size)
 {
     if (size == m_meshResolution)
diff --git a/src/imports/shaders/shadereffectsource.cpp b/src/imports/shaders/shadereffectsource.cpp
index 6210c41..7916538 100644
--- a/src/imports/shaders/shadereffectsource.cpp
+++ b/src/imports/shaders/shadereffectsource.cpp
@@ -105,11 +105,6 @@ ShaderEffectSource::~ShaderEffectSource()
     sourceItem regardless of its clipping property.
 */
 
-/*!
-    \property ShaderEffectSource::sourceItem
-    \brief the Item which is the source for the effect.
-*/
-
 void ShaderEffectSource::setSourceItem(QDeclarativeItem *item)
 {
     if (item == m_sourceItem)
@@ -159,11 +154,6 @@ void ShaderEffectSource::setSourceItem(QDeclarativeItem *item)
     The default value is Qt.rect(0,0,0,0).
 */
 
-/*!
-    \property ShaderEffectSource::sourceRect
-    \brief the relative sourceRect for the source.
-*/
-
 void ShaderEffectSource::setSourceRect(const QRectF &rect)
 {
     if (rect == m_sourceRect)
@@ -192,11 +182,6 @@ void ShaderEffectSource::setSourceRect(const QRectF &rect)
     The default value is QSize(0,0).
 */
 
-/*!
-    \property ShaderEffectSource::textureSize
-    \brief the texture size for the source.
-*/
-
 void ShaderEffectSource::setTextureSize(const QSize &size)
 {
     if (size == m_textureSize)
@@ -227,11 +212,6 @@ void ShaderEffectSource::setTextureSize(const QSize &size)
     The default value is true.
 */
 
-/*!
-    \property ShaderEffectSource::live
-    \brief the flag tells whether source item content is changing between frames.
-*/
-
 void ShaderEffectSource::setLive(bool s)
 {
     if (s == m_live)
@@ -251,11 +231,6 @@ void ShaderEffectSource::setLive(bool s)
     The default value is false.
 */
 
-/*!
-    \property ShaderEffectSource::hideSource
-    \brief the flag tells whether original source item content should be hidden.
-*/
-
 void ShaderEffectSource::setHideSource(bool hide)
 {
     if (hide == m_hideSource)
@@ -283,11 +258,6 @@ void ShaderEffectSource::setHideSource(bool hide)
 
 */
 
-/*!
-    \property ShaderEffectSource::wrapMode
-    \brief the wrap parameter for the source after it has been mapped as a texture.
-*/
-
 void ShaderEffectSource::setWrapMode(WrapMode mode)
 {
     if (mode == m_wrapMode)
diff --git a/src/network/kernel/qnetworkproxy.cpp b/src/network/kernel/qnetworkproxy.cpp
index 6d4df44..71d61a4 100644
--- a/src/network/kernel/qnetworkproxy.cpp
+++ b/src/network/kernel/qnetworkproxy.cpp
@@ -1197,6 +1197,11 @@ void QNetworkProxyQuery::setUrl(const QUrl &url)
 }
 
 #ifndef QT_NO_BEARERMANAGEMENT
+/*!
+    Returns the network configuration of the proxy query.
+
+    \sa setNetworkConfiguration()
+*/
 QNetworkConfiguration QNetworkProxyQuery::networkConfiguration() const
 {
     return d ? d->config : QNetworkConfiguration();
@@ -1214,7 +1219,7 @@ QNetworkConfiguration QNetworkProxyQuery::networkConfiguration() const
     you should first start the QNetworkSession and obtain the active
     configuration from its properties.
 
-    \sa networkConfiguration
+    \sa networkConfiguration()
 */
 void QNetworkProxyQuery::setNetworkConfiguration(const QNetworkConfiguration &networkConfiguration)
 {
diff --git a/src/sql/models/qsqlrelationaltablemodel.cpp b/src/sql/models/qsqlrelationaltablemodel.cpp
index 188259d..0edfaf4 100644
--- a/src/sql/models/qsqlrelationaltablemodel.cpp
+++ b/src/sql/models/qsqlrelationaltablemodel.cpp
@@ -710,24 +710,32 @@ void QSqlRelationalTableModel::clear()
 }
 
 
-/*! \enum QSqlRelationalTableModel::JoinMode
+/*!
+    \enum QSqlRelationalTableModel::JoinMode
+    \since 4.8
 
-    \value InnerJoin - Inner join mode, return rows when there is at least one match in both tables.
-    \value LeftJoin - Left join mode, returns all rows from the left table (table_name1), even if there are no matches in the right table (table_name2).
+    This enum specifies the type of mode to use when joining two tables.
 
-    \sa QSqlRelationalTableModel::setJoinMode
-    \since 4.8
+    \value InnerJoin Inner join mode, return rows when there is at least one
+                     match in both tables.
+    \value LeftJoin  Left join mode, returns all rows from the left table
+                     (table_name1), even if there are no matches in the right
+                     table (table_name2).
+
+    \sa QSqlRelationalTableModel::setJoinMode()
 */
 
 /*!
-    Sets the SQL join mode to show or hide rows with NULL foreign keys.
-    In InnerJoin mode (the default) these rows will not be showed: use the
+    \since 4.8
+    Sets the SQL join mode to the value given by \a joinMode to show or hide
+    rows with NULL foreign keys.
+
+    In InnerJoin mode (the default) these rows will not be shown; use the
     LeftJoin mode if you want to show them.
 
     \sa QSqlRelationalTableModel::JoinMode
-    \since 4.8
 */
-void QSqlRelationalTableModel::setJoinMode( QSqlRelationalTableModel::JoinMode joinMode )
+void QSqlRelationalTableModel::setJoinMode(QSqlRelationalTableModel::JoinMode joinMode)
 {
     Q_D(QSqlRelationalTableModel);
     d->joinMode = joinMode;
diff --git a/tools/qdoc3/test/qt-cpp-ignore.qdocconf b/tools/qdoc3/test/qt-cpp-ignore.qdocconf
index 044eef4..5b41ae3 100644
--- a/tools/qdoc3/test/qt-cpp-ignore.qdocconf
+++ b/tools/qdoc3/test/qt-cpp-ignore.qdocconf
@@ -73,7 +73,8 @@ Cpp.ignoretokens        = QAXFACTORY_EXPORT \
                           Q_DECLARATIVE_EXPORT \
                           Q_GADGET \
                           QWEBKIT_EXPORT \
-                          Q_INVOKABLE
+                          Q_INVOKABLE \
+                          Q_DECL_CONSTEXPR
 Cpp.ignoredirectives    = Q_DECLARE_HANDLE \
                           Q_DECLARE_INTERFACE \
                           Q_DECLARE_METATYPE \
diff --git a/tools/qdoc3/test/qt-project.qdocconf b/tools/qdoc3/test/qt-project.qdocconf
index fca6545..57bf797 100644
--- a/tools/qdoc3/test/qt-project.qdocconf
+++ b/tools/qdoc3/test/qt-project.qdocconf
@@ -105,7 +105,7 @@ exampledirs             = $QT_SOURCE_TREE/doc/src \
                           $QT_SOURCE_TREE/examples/tutorials \
                           $QT_SOURCE_TREE \
                           $QT_SOURCE_TREE/qmake/examples \
-                          $QT_SOURCE_TREE/src/3rdparty/webkit/WebKit/qt/docs
+                          $QT_SOURCE_TREE/src/3rdparty/webkit/Source/WebKit/qt/docs
 imagedirs               = $QT_SOURCE_TREE/doc/src/images \
                           $QT_SOURCE_TREE/examples \
                           $QT_SOURCE_TREE/doc/src/declarative/pics \