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>

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
+    \sa QLCDNumber, QObject::connect(), {Digital Clock Example},
-    {Tetrix Example}.
+    {Tetrix Example}
 
     \section1 Signals And Slots With Default Arguments
 

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:
 

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
+    Convenience function to both lock and bind the \a graphicsBuffer to a texture.
-    function will first try and lock with texture read and texture write
+    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
+    content to the currently bound texture, and if \a premultiplied is provided,
-    with SWReadAccess and then use the bindSWToTexture convenience function.
+    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
+    Red and Blue channels are swapped. Conveniently, the Alpha buffer will be
-    correct since Qt historically has had the alpha channel as the first
+    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
+    \a subRect is the region to be bound to the texture. This argument has a
-    argument has a no less than semantic, meaning more (if not all) of the buffer
+    not less than semantic, meaning more (if not all) of the buffer can be
-    can be bounded to the texture. An empty QRect is interpreted as entire buffer
+    bound to the texture. An empty QRect is interpreted as meaning the entire
-    should be bound.
+    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,

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,

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.

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.
 

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.

src/widgets/widgets/qabstractspinbox.cpp

@@ -126,6 +126,13 @@ QT_BEGIN_NAMESPACE
     \value StepDownEnabled
 */
 
+/*!
+    \enum QAbstractSpinBox::StepType
+
+    \value DefaultStepType
+    \value AdaptiveDecimalStepType
+*/
+
 /*!
   \fn void QAbstractSpinBox::editingFinished()
 

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

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.

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
 

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
+    Sets the step type for the spin box to \a stepType, which is single
-    decimal step.
+    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
+    Sets the step type for the spin box to \a stepType, which is single
-    decimal step.
+    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);

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.
 */