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 <[email protected]>

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
 

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
-    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,

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 @@ class Q_WIDGETS_EXPORT QMenu : public QWidget
     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 @@ class Q_WIDGETS_EXPORT QMenu : public QWidget
         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 @@ class Q_WIDGETS_EXPORT QMenu : public QWidget
     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 @@
 
 
 /*!
+    \fn NSMenu *QMenu::toNSMenu()
     \since 5.2
 
     Returns the native NSMenu for this menu. Available on \macos only.
@@ -94,6 +95,7 @@
 
 
 /*!
+    \fn void QMenu::setAsDockMenu()
     \since 5.2
 
     Set this menu to be the dock menu available by option-clicking
@@ -149,6 +151,7 @@
 #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 @@ class Q_WIDGETS_EXPORT QMenuBar : public QWidget
     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 @@ class Q_WIDGETS_EXPORT QMenuBar : public QWidget
         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 @@ class Q_WIDGETS_EXPORT QMenuBar : public QWidget
     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
-    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);

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