Doc: Fixed qdoc warnings.

8 files changed, 82 insertions, 44 deletions

diff --git a/src/corelib/tools/qlocale.qdoc b/src/corelib/tools/qlocale.qdoc
index 605e3e0..1d5e5c5 100644
--- a/src/corelib/tools/qlocale.qdoc
+++ b/src/corelib/tools/qlocale.qdoc
@@ -769,6 +769,8 @@
   \value Weekdays a QList<Qt::DayOfWeek> specifying the regular weekdays
   \value LocaleChanged this type is queried whenever the system locale is changed.
   \value ListToSeparatedString a string that represents a join of a given QStringList with a locale-defined separator.
+  \value NativeLanguageName a string that represents the name of the native language.
+  \value NativeCountryName a string that represents the name of the native country.
 */
 
 /*!
diff --git a/src/dbus/qdbusconnection.cpp b/src/dbus/qdbusconnection.cpp
index c8cf6ea..009d9b8 100644
--- a/src/dbus/qdbusconnection.cpp
+++ b/src/dbus/qdbusconnection.cpp
@@ -234,10 +234,11 @@ void QDBusConnectionManager::setConnection(const QString &name, QDBusConnectionP
 
 /*!
     \since 4.8
-    \enum QDBusConnection::ConnectionCapabilities
-    The available capabilities for a D-Bus connection.
+    \enum QDBusConnection::ConnectionCapability
 
-    \value UnixFileDescriptorPassing        passing of Unix file descriptors to other processes
+    This enum describes the available capabilities for a D-Bus connection.
+
+    \value UnixFileDescriptorPassing        enables passing of Unix file descriptors to other processes
                                             (see QDBusUnixFileDescriptor)
 
     \sa connectionCapabilities()
diff --git a/src/dbus/qdbusunixfiledescriptor.cpp b/src/dbus/qdbusunixfiledescriptor.cpp
index a22b4ab..178a663 100644
--- a/src/dbus/qdbusunixfiledescriptor.cpp
+++ b/src/dbus/qdbusunixfiledescriptor.cpp
@@ -102,6 +102,16 @@ QT_BEGIN_NAMESPACE
     \sa QDBusConnection::ConnectionCapabilities, QDBusConnection::connectionCapabilities()
 */
 
+/*!
+    \typedef QDBusUnixFileDescriptor::Data
+    \internal
+*/
+
+/*!
+    \variable QDBusUnixFileDescriptor::d
+    \internal
+*/
+
 class QDBusUnixFileDescriptorPrivate : public QSharedData {
 public:
     QDBusUnixFileDescriptorPrivate() : fd(-1) { }
diff --git a/src/gui/kernel/qplatformcursor_qpa.cpp b/src/gui/kernel/qplatformcursor_qpa.cpp
index f430f6e..13317b8 100644
--- a/src/gui/kernel/qplatformcursor_qpa.cpp
+++ b/src/gui/kernel/qplatformcursor_qpa.cpp
@@ -89,9 +89,9 @@ QList <QWeakPointer<QPlatformCursor> > QPlatformCursorPrivate::instances;
 */
 
 /*!
-    \fn QPlatformCursor::QPlatformCursor()
+    \fn QPlatformCursor::QPlatformCursor(QPlatformScreen *screen)
 
-    \brief Constructs a QPlatformCursor
+    Constructs a QPlatformCursor for the given \a screen.
 */
 QPlatformCursor::QPlatformCursor(QPlatformScreen *scr )
         : screen(scr)
@@ -615,22 +615,11 @@ void QPlatformCursorImage::set(const uchar *data, const uchar *mask,
 /*!
     \fn QPlatformCursorImage::QPlatformCursorImage(const uchar *data, const uchar *mask, int width, int height, int hotX, int hotY)
 
-    \brief set the cursor image to the graphic represented by the combination of data, mask,
-    width, and height
-
-    \a data The pixel data of the graphic
-
-    \a mask Mask data for the graphic. pixels in data with a corresponding mask bit of 0 are not drawn
-
-    \a width The width of the graphic in pixels
-
-    \a height The height of the graphic in pixels
-
-    \a hotX The X hotspot of the cursor graphic
-
-    \a hotY The Y hotspot of the cursor graphic
+    Sets the cursor image to the graphic represented by the combination of
+    \a data and \a mask, with dimensions given by \a width and \a height and a
+    hotspot at the point specified by (\a hotX, \a hotY).
 
-    \sa set
+    \sa set()
 */
 
 /*!
diff --git a/src/gui/kernel/qplatformwindowformat_qpa.cpp b/src/gui/kernel/qplatformwindowformat_qpa.cpp
index b9ddeea..1a4c97e 100644
--- a/src/gui/kernel/qplatformwindowformat_qpa.cpp
+++ b/src/gui/kernel/qplatformwindowformat_qpa.cpp
@@ -122,8 +122,6 @@ public:
     \i \link setStencil() Stencil buffer.\endlink
     \i \link setStereo() Stereo buffers.\endlink
     \i \link setDirectRendering() Direct rendering.\endlink
-    \i \link setOverlay() Presence of an overlay.\endlink
-    \i \link setPlane() Plane of an overlay.\endlink
     \i \link setSampleBuffers() Multisample buffers.\endlink
     \endlist
 
@@ -168,7 +166,7 @@ public:
         United States and other countries.
     \endlegalese
 
-    \sa QPlatformContext, QWidget
+    \sa QPlatformGLContext, QWidget
 */
 
 /*!
@@ -182,8 +180,6 @@ public:
     \i \link setStencil() Stencil buffer:\endlink Enabled.
     \i \link setStereo() Stereo:\endlink Disabled.
     \i \link setDirectRendering() Direct rendering:\endlink Enabled.
-    \i \link setOverlay() Overlay:\endlink Disabled.
-    \i \link setPlane() Plane:\endlink 0 (i.e., normal plane).
     \i \link setSampleBuffers() Multisample buffers:\endlink Disabled.
     \endlist
 */
@@ -207,14 +203,10 @@ QPlatformWindowFormat::QPlatformWindowFormat()
     \snippet doc/src/snippets/code/src_opengl_qgl.cpp 3
 
     Note that there are QGL::FormatOption values to turn format settings
-    both on and off, e.g. QGL::DepthBuffer and QGL::NoDepthBuffer,
+    both on and off; e.g., QGL::DepthBuffer and QGL::NoDepthBuffer,
     QGL::DirectRendering and QGL::IndirectRendering, etc.
 
-    The \a plane parameter defaults to 0 and is the plane which this
-    format should be associated with. Not all OpenGL implementations
-    supports overlay/underlay rendering planes.
-
-    \sa defaultFormat(), setOption(), setPlane()
+    \sa defaultFormat(), setOption()
 */
 
 QPlatformWindowFormat::QPlatformWindowFormat(QPlatformWindowFormat::FormatOptions options)
@@ -619,8 +611,6 @@ QPlatformGLContext *QPlatformWindowFormat::sharedGLContext() const
     Otherwise returns false.
 
     WindowSurface is enabled by default.
-
-    \sa setOverlay()
 */
 
 /*!
@@ -628,9 +618,7 @@ QPlatformGLContext *QPlatformWindowFormat::sharedGLContext() const
 
     otherwise the QWidget will only have a QPlatformWindow.
 
-    This is useful for ie. QGLWidget where the QPlatformGLContext controls the surface.
-
-    \sa hasOverlay()
+    This is useful for QGLWidget where the QPlatformGLContext controls the surface.
 */
 
 void QPlatformWindowFormat::setWindowSurface(bool enable)
@@ -907,9 +895,7 @@ void QPlatformWindowFormat::setDefaultFormat(const QPlatformWindowFormat &f)
     \i \link setStencil() Stencil buffer:\endlink Disabled.
     \i \link setStereo() Stereo:\endlink Disabled.
     \i \link setDirectRendering() Direct rendering:\endlink Enabled.
-    \i \link setOverlay() Overlay:\endlink Disabled.
     \i \link setSampleBuffers() Multisample buffers:\endlink Disabled.
-    \i \link setPlane() Plane:\endlink 1 (i.e., first overlay plane).
     \endlist
 
     \sa setDefaultFormat()
diff --git a/src/gui/kernel/qwidget_qpa.cpp b/src/gui/kernel/qwidget_qpa.cpp
index 001810e..321eaa3 100644
--- a/src/gui/kernel/qwidget_qpa.cpp
+++ b/src/gui/kernel/qwidget_qpa.cpp
@@ -681,8 +681,10 @@ int QWidget::metric(PaintDeviceMetric m) const
 /*!
     \preliminary
 
-    Sets the window to be the \a window specified.
-    The QWidget takes ownership of the \a surface.
+    Sets the window to be the platform \a window specified.
+
+    The widget takes ownership of the \a window. Any platform window
+    previously set on the widget will be destroyed.
 */
 void QWidget::setPlatformWindow(QPlatformWindow *window)
 {
@@ -711,6 +713,9 @@ QPlatformWindow *QWidget::platformWindow() const
     return 0;
 }
 
+/*!
+    Sets the platform window format for the widget to the \a format specified.
+*/
 void QWidget::setPlatformWindowFormat(const QPlatformWindowFormat &format)
 {
     if (isWindow() || testAttribute(Qt::WA_NativeWindow)) {
@@ -727,6 +732,9 @@ void QWidget::setPlatformWindowFormat(const QPlatformWindowFormat &format)
     }
 }
 
+/*!
+    Returns the platform window format for the widget.
+*/
 QPlatformWindowFormat QWidget::platformWindowFormat() const
 {
     Q_D(const QWidget);
diff --git a/src/gui/text/qplatformfontdatabase_qpa.cpp b/src/gui/text/qplatformfontdatabase_qpa.cpp
index ea115c4..dcee335 100644
--- a/src/gui/text/qplatformfontdatabase_qpa.cpp
+++ b/src/gui/text/qplatformfontdatabase_qpa.cpp
@@ -51,6 +51,13 @@ extern void qt_registerFont(const QString &familyname, const QString &foundrynam
                                          QFont::Style style, int stretch, bool antialiased,bool scalable, int pixelSize,
                                          const QSupportedWritingSystems &writingSystems, void *hanlde);
 
+/*!
+    \fn void QPlatformFontDatabase::registerQPF2Font(const QByteArray &dataArray, void *)
+
+    Registers the pre-rendered QPF2 font contained in the given \a dataArray.
+
+    \sa registerFont()
+*/
 void QPlatformFontDatabase::registerQPF2Font(const QByteArray &dataArray, void *handle)
 {
     if (dataArray.size() == 0)
@@ -88,6 +95,32 @@ void QPlatformFontDatabase::registerQPF2Font(const QByteArray &dataArray, void *
     }
 }
 
+/*!
+    \fn void QPlatformFontDatabase::registerFont(const QString &familyName,
+        const QString &foundryName, QFont::Weight weight, QFont::Style style,
+        QFont::Stretch stretch, bool antialiased, bool scalable, int pixelSize,
+        const QSupportedWritingSystems &writingSystems, void *usrPtr)
+
+    Registers a font with the given set of attributes describing the font's
+    foundry, family name, style and stretch information, pixel size, and
+    supported writing systems. Additional information about whether the font
+    can be scaled and antialiased can also be provided.
+
+    The foundry name and font family are described by \a foundryName and
+    \a familyName. The font weight (light, normal, bold, etc.), style (normal,
+    oblique, italic) and stretch information (condensed, expanded, unstretched,
+    etc.) are specified by \a weight, \a style and \a stretch.
+
+    Some fonts can be antialiased and scaled; \a scalable and \a antialiased
+    can be set to true for fonts with these attributes. The intended pixel
+    size of non-scalable fonts is specified by \a pixelSize; this value will be
+    ignored for scalable fonts.
+
+    The writing systems supported by the font are specified by the
+    \a writingSystems argument.
+
+    \sa registerQPF2Font()
+*/
 void QPlatformFontDatabase::registerFont(const QString &familyname, const QString &foundryname, QFont::Weight weight,
                                          QFont::Style style, QFont::Stretch stretch, bool antialiased, bool scalable, int pixelSize,
                                          const QSupportedWritingSystems &writingSystems, void *usrPtr)
@@ -243,10 +276,13 @@ QStringList QPlatformFontDatabase::fallbacksForFamily(const QString family, cons
 }
 
 /*!
-    Adds an application font described by the given \a fontData that can be
-    referenced using the specified \a fontName, which is the name for the font
-    family. Returns a list of family names, or an empty list if the font could
-    not be added
+    Adds an application font described by the font contained supplied \a fontData
+    or using the font contained in the file referenced by \a fileName. Returns
+    a list of family names, or an empty list if the font could not be added.
+
+    \note The default implementation of this function does not add an application
+    font. Subclasses should reimplement this function to perform the necessary
+    loading and registration of fonts.
 */
 QStringList QPlatformFontDatabase::addApplicationFont(const QByteArray &fontData, const QString &fileName)
 {
diff --git a/src/opengl/qgl_qpa.cpp b/src/opengl/qgl_qpa.cpp
index 24a4f5e..3778072 100644
--- a/src/opengl/qgl_qpa.cpp
+++ b/src/opengl/qgl_qpa.cpp
@@ -52,6 +52,9 @@
 
 QT_BEGIN_NAMESPACE
 
+/*!
+    Returns an OpenGL format for the platform window format specified by \a format.
+*/
 QGLFormat QGLFormat::fromPlatformWindowFormat(const QPlatformWindowFormat &format)
 {
     QGLFormat retFormat;
@@ -83,6 +86,9 @@ QGLFormat QGLFormat::fromPlatformWindowFormat(const QPlatformWindowFormat &forma
     return retFormat;
 }
 
+/*!
+    Returns a platform window format for the OpenGL format specified by \a format.
+*/
 QPlatformWindowFormat QGLFormat::toPlatformWindowFormat(const QGLFormat &format)
 {
     QPlatformWindowFormat retFormat;