qdoc: Fix several minor errors to reduce qdoc warnings

This update corrects several minor documentation errors that
cause qdoc warnings. These include incorrect or missing \fn
commands, incorrect uses of \e and \a commands together,
incorrect spellings, etc.

Change-Id: Ib26edef541fa3440025490bcf79cc101623e7f7b
Reviewed-by: Martin Smith <martin.smith@qt.io>

13 files changed, 71 insertions, 41 deletions

diff --git a/src/corelib/doc/src/objectmodel/signalsandslots.qdoc b/src/corelib/doc/src/objectmodel/signalsandslots.qdoc
index 213caa6c59..fcf091458a 100644
--- a/src/corelib/doc/src/objectmodel/signalsandslots.qdoc
+++ b/src/corelib/doc/src/objectmodel/signalsandslots.qdoc
@@ -321,8 +321,8 @@
     callbacks, you'd have to find five different names and keep track
     of the types yourself.
 
-    \sa QLCDNumber, QObject::connect(), {Digital Clock Example}, and
-    {Tetrix Example}.
+    \sa QLCDNumber, QObject::connect(), {Digital Clock Example},
+    {Tetrix Example}
 
     \section1 Signals And Slots With Default Arguments
 
diff --git a/src/corelib/global/qglobal.cpp b/src/corelib/global/qglobal.cpp
index 9cbfda3c2c..d197688316 100644
--- a/src/corelib/global/qglobal.cpp
+++ b/src/corelib/global/qglobal.cpp
@@ -3814,14 +3814,14 @@ bool qunsetenv(const char *varName)
 
     Marks the UTF-8 encoded string literal \a sourceText for numerator
     dependent delayed translation in the given \a context with the given
-    \a disambiguation.
+    \a comment.
     The \a context is typically a class and also needs to be specified
     as a string literal. The string literal \a disambiguation should be
     a short semantic tag to tell apart otherwise identical strings.
 
     The macro tells lupdate to collect the string, and expands to an
     anonymous struct of the two string literals passed as \a sourceText
-    and \a disambiguation.
+    and \a comment.
 
     Example:
 
diff --git a/src/gui/kernel/qplatformgraphicsbufferhelper.cpp b/src/gui/kernel/qplatformgraphicsbufferhelper.cpp
index 2afb5e6ba5..924266997d 100644
--- a/src/gui/kernel/qplatformgraphicsbufferhelper.cpp
+++ b/src/gui/kernel/qplatformgraphicsbufferhelper.cpp
@@ -57,24 +57,28 @@
 QT_BEGIN_NAMESPACE
 
 /*!
-    Convenience function to both lock and bind the buffer to a texture. This
-    function will first try and lock with texture read and texture write
+    Convenience function to both lock and bind the \a graphicsBuffer to a texture.
+    This function will first try to lock with texture read and texture write
     access. If this succeeds it will use the bindToTexture function to bind the
-    content to the currently bound texture. If this fail it will try and lock
-    with SWReadAccess and then use the bindSWToTexture convenience function.
+    content to the currently bound texture, and if \a premultiplied is provided,
+    it is set to false.
 
-    \a swizzle is suppose to be used by the caller to figure out if the Red and
+    If it fails, it will try to lock with SWReadAccess and then use the
+    bindSWToTexture convenience function. If \a premultiplied is provided, it is
+    passed to the bindSWToTexture() function.
+
+    \a swizzle is meant to be used by the caller to figure out if the Red and
     Blue color channels need to be swizzled when rendering.
 
     \a rect is the subrect which is desired to be bounded to the texture. This
-    argument has a no less than semantic, meaning more (if not all) of the buffer
+    argument has a not less than semantic, meaning more (if not all) of the buffer
     can be bounded to the texture. An empty QRect is interpreted as entire buffer
     should be bound.
 
     The user should use the AccessTypes returned by isLocked to figure out what
     lock has been obtained.
 
-    returns true if the buffer has successfully been bound to the currently
+    Returns true if the buffer has successfully been bound to the currently
     bound texture, otherwise returns false.
 */
 bool QPlatformGraphicsBufferHelper::lockAndBindToTexture(QPlatformGraphicsBuffer *graphicsBuffer,
@@ -103,26 +107,29 @@ bool QPlatformGraphicsBufferHelper::lockAndBindToTexture(QPlatformGraphicsBuffer
 }
 
 /*!
-    Convenience function that uploads the current raster content to the currently bound texture.
+    Convenience function that uploads the current raster content to the currently
+    bound texture.
 
-    \a swizzleRandB is suppose to be used by the caller to figure out if the Red and
+    \a swizzleRandB is meant to be used by the caller to decide if the Red and
     Blue color channels need to be swizzled when rendering. This is an
     optimization. Qt often renders to software buffers interpreting pixels as
     unsigned ints. When these buffers are uploaded to textures and each color
     channel per pixel is interpreted as a byte (read sequentially), then the
-    Red and Blue channels are swapped. Conveniently the Alpha buffer will be
-    correct since Qt historically has had the alpha channel as the first
+    Red and Blue channels are swapped. Conveniently, the Alpha buffer will be
+    correct, since Qt historically has had the alpha channel as the first
     channel, while OpenGL typically expects the alpha channel to be the last
     channel.
 
-    \a subRect is the subrect which is desired to be bounded to the texture. This
-    argument has a no less than semantic, meaning more (if not all) of the buffer
-    can be bounded to the texture. An empty QRect is interpreted as entire buffer
-    should be bound.
+    \a subRect is the region to be bound to the texture. This argument has a
+    not less than semantic, meaning more (if not all) of the buffer can be
+    bound to the texture. An empty QRect is interpreted as meaning the entire
+    buffer should be bound.
 
-    This function fails for buffers not capable of locking to SWAccess.
+    This function fails if the \a graphicsBuffer is not locked to SWAccess.
 
-    Returns true on success, otherwise false.
+    Returns true on success, otherwise false. If \a premultipliedB is
+    provided, it is set according to what happens, if the function returns
+    true.
 */
 bool QPlatformGraphicsBufferHelper::bindSWToTexture(const QPlatformGraphicsBuffer *graphicsBuffer,
                                                     bool *swizzleRandB, bool *premultipliedB,
diff --git a/src/network/ssl/qssl.h b/src/network/ssl/qssl.h
index 8ab24d89e1..dd268cd86d 100644
--- a/src/network/ssl/qssl.h
+++ b/src/network/ssl/qssl.h
@@ -91,7 +91,7 @@ namespace QSsl {
         TlsV1_1OrLater,
         TlsV1_2OrLater,
 
-#if QT_CONFIG(dtls)
+#if QT_CONFIG(dtls) || defined(Q_CLANG_QDOC)
         DtlsV1_0,
         DtlsV1_0OrLater,
         DtlsV1_2,
diff --git a/src/widgets/dialogs/qcolordialog.cpp b/src/widgets/dialogs/qcolordialog.cpp
index e6a8ec47a4..434cedfdb9 100644
--- a/src/widgets/dialogs/qcolordialog.cpp
+++ b/src/widgets/dialogs/qcolordialog.cpp
@@ -2170,7 +2170,7 @@ QColor QColorDialog::getColor(const QColor &initial, QWidget *parent, const QStr
     and an alpha channel (transparency) value. The color+alpha is
     initially set to \a initial. The dialog is a child of \a parent.
 
-    If \a ok is non-null, \e *\a ok is set to true if the user clicked
+    If \a ok is non-null, \e {*ok} is set to true if the user clicked
     \uicontrol{OK}, and to false if the user clicked Cancel.
 
     If the user clicks Cancel, the \a initial value is returned.
diff --git a/src/widgets/dialogs/qinputdialog.cpp b/src/widgets/dialogs/qinputdialog.cpp
index 5c6e0f45a5..9a9bd173bd 100644
--- a/src/widgets/dialogs/qinputdialog.cpp
+++ b/src/widgets/dialogs/qinputdialog.cpp
@@ -1180,7 +1180,7 @@ void QInputDialog::done(int result)
     \a inputMethodHints is the input method hints that will be used in the
     edit widget if an input method is active.
 
-    If \a ok is nonnull \e *\a ok will be set to true if the user pressed
+    If \a ok is nonnull \e {*ok} will be set to true if the user pressed
     \uicontrol OK and to false if the user pressed \uicontrol Cancel. The dialog's parent
     is \a parent. The dialog will be modal and uses the specified widget
     \a flags.
@@ -1228,7 +1228,7 @@ QString QInputDialog::getText(QWidget *parent, const QString &title, const QStri
     \a inputMethodHints is the input method hints that will be used in the
     edit widget if an input method is active.
 
-    If \a ok is nonnull \e *\a ok will be set to true if the user pressed
+    If \a ok is nonnull \e {*ok} will be set to true if the user pressed
     \uicontrol OK and to false if the user pressed \uicontrol Cancel. The dialog's parent
     is \a parent. The dialog will be modal and uses the specified widget
     \a flags.
@@ -1436,7 +1436,7 @@ double QInputDialog::getDouble(QWidget *parent, const QString &title, const QStr
     If \a editable is true the user can enter their own text; otherwise, the
     user may only select one of the existing items.
 
-    If \a ok is nonnull \e *\a ok will be set to true if the user pressed
+    If \a ok is nonnull \e {*ok} will be set to true if the user pressed
     \uicontrol OK and to false if the user pressed \uicontrol Cancel. The dialog's parent
     is \a parent. The dialog will be modal and uses the widget \a flags.
 
diff --git a/src/widgets/itemviews/qtreewidget.cpp b/src/widgets/itemviews/qtreewidget.cpp
index d0728b1af2..a0af27115d 100644
--- a/src/widgets/itemviews/qtreewidget.cpp
+++ b/src/widgets/itemviews/qtreewidget.cpp
@@ -1001,6 +1001,7 @@ void QTreeModel::timerEvent(QTimerEvent *ev)
 */
 
 /*!
+  \fn void QTreeWidgetItem::setHidden(bool hide)
   \since 4.2
 
   Hides the item if \a hide is true, otherwise shows the item.
diff --git a/src/widgets/widgets/qabstractspinbox.cpp b/src/widgets/widgets/qabstractspinbox.cpp
index 822d896ee6..1eafb73ba8 100644
--- a/src/widgets/widgets/qabstractspinbox.cpp
+++ b/src/widgets/widgets/qabstractspinbox.cpp
@@ -127,6 +127,13 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
+    \enum QAbstractSpinBox::StepType
+
+    \value DefaultStepType
+    \value AdaptiveDecimalStepType
+*/
+
+/*!
   \fn void QAbstractSpinBox::editingFinished()
 
   This signal is emitted editing is finished. This happens when the
diff --git a/src/widgets/widgets/qmenu.h b/src/widgets/widgets/qmenu.h
index 86d927e919..628f818b5e 100644
--- a/src/widgets/widgets/qmenu.h
+++ b/src/widgets/widgets/qmenu.h
@@ -46,7 +46,7 @@
 #include <QtGui/qicon.h>
 #include <QtWidgets/qaction.h>
 
-#ifdef Q_OS_OSX
+#if defined(Q_OS_MACOS) || defined(Q_CLANG_QDOC)
 Q_FORWARD_DECLARE_OBJC_CLASS(NSMenu);
 #endif
 
@@ -81,7 +81,7 @@ public:
     QAction *addAction(const QString &text, const QObject *receiver, const char* member, const QKeySequence &shortcut = 0);
     QAction *addAction(const QIcon &icon, const QString &text, const QObject *receiver, const char* member, const QKeySequence &shortcut = 0);
 
-#ifdef Q_QDOC
+#ifdef Q_CLANG_QDOC
     template<typename PointerToMemberFunction>
     QAction *addAction(const QString &text, const QObject *receiver, PointerToMemberFunction method, const QKeySequence &shortcut = 0);
     template<typename Functor>
@@ -151,7 +151,7 @@ public:
         connect(result, &QAction::triggered, std::move(slot));
         return result;
     }
-#endif // !Q_QDOC
+#endif // !Q_CLANG_QDOC
 
     QAction *addMenu(QMenu *menu);
     QMenu *addMenu(const QString &title);
@@ -211,7 +211,7 @@ public:
     QPlatformMenu *platformMenu();
     void setPlatformMenu(QPlatformMenu *platformMenu);
 
-#ifdef Q_OS_OSX
+#if defined(Q_OS_MACOS) || defined(Q_CLANG_QDOC)
     NSMenu* toNSMenu();
     void setAsDockMenu();
 #endif
diff --git a/src/widgets/widgets/qmenu_mac.mm b/src/widgets/widgets/qmenu_mac.mm
index 0d680fb4dc..0872da803d 100644
--- a/src/widgets/widgets/qmenu_mac.mm
+++ b/src/widgets/widgets/qmenu_mac.mm
@@ -73,6 +73,7 @@ inline QPlatformNativeInterface::NativeResourceForIntegrationFunction resolvePla
 
 
 /*!
+    \fn NSMenu *QMenu::toNSMenu()
     \since 5.2
 
     Returns the native NSMenu for this menu. Available on \macos only.
@@ -94,6 +95,7 @@ NSMenu *QMenu::toNSMenu()
 
 
 /*!
+    \fn void QMenu::setAsDockMenu()
     \since 5.2
 
     Set this menu to be the dock menu available by option-clicking
@@ -149,6 +151,7 @@ void QMenuPrivate::moveWidgetToPlatformItem(QWidget *widget, QPlatformMenuItem*
 #if QT_CONFIG(menubar)
 
 /*!
+    \fn NSMenu *QMenuBar::toNSMenu()
     \since 5.2
 
     Returns the native NSMenu for this menu bar. Available on \macos only.
diff --git a/src/widgets/widgets/qmenubar.h b/src/widgets/widgets/qmenubar.h
index 2f071e7e3b..cf6663f94a 100644
--- a/src/widgets/widgets/qmenubar.h
+++ b/src/widgets/widgets/qmenubar.h
@@ -67,7 +67,7 @@ public:
     QAction *addAction(const QString &text);
     QAction *addAction(const QString &text, const QObject *receiver, const char* member);
 
-#ifdef Q_QDOC
+#ifdef Q_CLANG_QDOC
     template<typename Obj, typename PointerToMemberFunctionOrFunctor>
     QAction *addAction(const QString &text, const Obj *receiver, PointerToMemberFunctionOrFunctor method);
     template<typename Functor>
@@ -91,7 +91,7 @@ public:
         connect(result, &QAction::triggered, std::move(slot));
         return result;
     }
-#endif // !Q_QDOC
+#endif // !Q_CLANG_QDOC
 
     QAction *addMenu(QMenu *menu);
     QMenu *addMenu(const QString &title);
@@ -121,7 +121,7 @@ public:
     void setCornerWidget(QWidget *w, Qt::Corner corner = Qt::TopRightCorner);
     QWidget *cornerWidget(Qt::Corner corner = Qt::TopRightCorner) const;
 
-#ifdef Q_OS_OSX
+#if defined(Q_OS_MACOS) || defined(Q_CLANG_QDOC)
     NSMenu* toNSMenu();
 #endif
 
diff --git a/src/widgets/widgets/qspinbox.cpp b/src/widgets/widgets/qspinbox.cpp
index 7f29c0c52c..dcf3906dd7 100644
--- a/src/widgets/widgets/qspinbox.cpp
+++ b/src/widgets/widgets/qspinbox.cpp
@@ -421,8 +421,8 @@ void QSpinBox::setRange(int minimum, int maximum)
 }
 
 /*!
-    Sets the step type for the spin box: single step or adaptive
-    decimal step.
+    Sets the step type for the spin box to \a stepType, which is single
+    step or adaptive decimal step.
 
     Adaptive decimal step means that the step size will continuously be
     adjusted to one power of ten below the current \l value. So when
@@ -439,7 +439,6 @@ void QSpinBox::setRange(int minimum, int maximum)
     \l singleStep, although it is preserved so that \l singleStep
     comes into effect if adaptive decimal step is later turned off.
 
-    \sa QAbstractSpinBox::groupSeparator()
     \since 5.12
 */
 
@@ -449,6 +448,13 @@ void QSpinBox::setStepType(QAbstractSpinBox::StepType stepType)
     d->stepType = stepType;
 }
 
+/*!
+    \property QSpinBox::stepType
+    \brief The step type.
+
+    The step type can be single step or adaptive decimal step.
+*/
+
 QAbstractSpinBox::StepType QSpinBox::stepType() const
 {
     Q_D(const QSpinBox);
@@ -888,8 +894,8 @@ void QDoubleSpinBox::setRange(double minimum, double maximum)
 }
 
 /*!
-    Sets the step type for the spin box: single step or adaptive
-    decimal step.
+    Sets the step type for the spin box to \a stepType, which is single
+    step or adaptive decimal step.
 
     Adaptive decimal step means that the step size will continuously be
     adjusted to one power of ten below the current \l value. So when
@@ -909,7 +915,6 @@ void QDoubleSpinBox::setRange(double minimum, double maximum)
     \l singleStep, although it is preserved so that \l singleStep
     comes into effect if adaptive decimal step is later turned off.
 
-    \sa QAbstractSpinBox::groupSeparator()
     \since 5.12
 */
 
@@ -919,6 +924,13 @@ void QDoubleSpinBox::setStepType(StepType stepType)
     d->stepType = stepType;
 }
 
+/*!
+    \property QDoubleSpinBox::stepType
+    \brief The step type.
+
+    The step type can be single step or adaptive decimal step.
+*/
+
 QAbstractSpinBox::StepType QDoubleSpinBox::stepType() const
 {
     Q_D(const QDoubleSpinBox);
diff --git a/src/xml/doc/src/xml-processing.qdoc b/src/xml/doc/src/xml-processing.qdoc
index 00c73b4465..4dfcbf4722 100644
--- a/src/xml/doc/src/xml-processing.qdoc
+++ b/src/xml/doc/src/xml-processing.qdoc
@@ -376,7 +376,7 @@
             reported through the handler.
     \endtable
 
-    The \l{SAX Bookmarks example} illustrates how to subclass
+    The \l{SAX Bookmarks Example} illustrates how to subclass
     QXmlDefaultHandler to read an XML bookmark file (XBEL) and
     how to generate XML by hand.
 
@@ -606,7 +606,7 @@
     DOM implementation.
 
     To get started please refer to the \l QDomDocument documentation.
-    You might also want to take a look at the \l{DOM Bookmarks example},
+    You might also want to take a look at the \l{DOM Bookmarks Example},
     which illustrates how to read and write an XML bookmark file (XBEL)
     using DOM.
 */