doc: Fix many qdoc warnings, mostly missing return types

Fixed many cases of missing return types in \fn commands.
Added a fake GLxxx typedef for a GL type that wasn't there
because the GL includes weren't accessible. Also added some
fake declarations for a few functions declared in namespace
Qt in QtWidgets that must be seen by qdoc in QtCore.

Change-Id: Id82476042d0563d32fa85c4ae81a58c1298a468a
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

src/corelib/global/qnamespace.h

@@ -1861,6 +1861,16 @@ public:
     static bool activateCallbacks(Callback, void **);
 };
 
+#if defined(Q_CLANG_QDOC)
+// Declared here for qdoc; actual declarations in qtextdocument.h
+namespace Qt
+{
+    bool mightBeRichText(const QString&);
+    QString convertFromPlainText(const QString &plain, WhiteSpaceMode mode = WhiteSpacePre);
+    QTextCodec *codecForHtml(const QByteArray &ba);
+}
+#endif // Q_CLANG_QDOC
+
 QT_END_NAMESPACE
 
 #endif // QNAMESPACE_H

src/corelib/global/qnamespace.qdoc

@@ -3222,3 +3222,37 @@
 
   \value ChecksumItuV41 Checksum calculation based on ITU-V.41.
 */
+
+/*!
+    \fn bool Qt::mightBeRichText(const QString& text)
+
+    Returns \c true if the string \a text is likely to be rich text;
+    otherwise returns \c false.
+
+    This function uses a fast and therefore simple heuristic. It
+    mainly checks whether there is something that looks like a tag
+    before the first line break. Although the result may be correct
+    for common cases, there is no guarantee.
+
+    This function is defined in the \c <QTextDocument> header file.
+*/
+
+/*!
+    \fn QString Qt::convertFromPlainText(const QString &plain, Qt::WhiteSpaceMode mode)
+
+    Converts the plain text string \a plain to an HTML-formatted
+    paragraph while preserving most of its look.
+
+    \a mode defines how whitespace is handled.
+
+    This function is defined in the \c <QTextDocument> header file.
+
+    \sa escape(), mightBeRichText()
+*/
+
+/*!
+    \fn QTextCodec *Qt::codecForHtml(const QByteArray &ba)
+    \internal
+
+    This function is defined in the \c <QTextDocument> header file.
+*/

src/gui/kernel/qcursor.cpp

@@ -171,6 +171,12 @@ QT_BEGIN_NAMESPACE
     \since 5.2
 */
 
+/*!
+  \fn void QCursor::swap(QCursor &other)
+
+  Swaps this cursor with the \a other cursor.
+ */
+
 /*!
     \fn QPoint QCursor::pos(const QScreen *screen)
 

src/gui/opengl/qopenglfunctions.h

@@ -234,6 +234,8 @@ typedef int GLint;
 typedef int GLsizei;
 #undef GLuint
 typedef unsigned int GLuint;
+#undef GLubyte
+typedef unsigned int GLubyte;
 #undef GLenum
 typedef unsigned int GLenum;
 #undef GLbitfield

src/gui/text/qtextdocument.cpp

@@ -73,19 +73,6 @@ QT_BEGIN_NAMESPACE
 
 Q_CORE_EXPORT Q_DECL_CONST_FUNCTION unsigned int qt_int_sqrt(unsigned int n);
 
-/*!
-    \fn bool Qt::mightBeRichText(const QString& text)
-
-    Returns \c true if the string \a text is likely to be rich text;
-    otherwise returns \c false.
-
-    This function uses a fast and therefore simple heuristic. It
-    mainly checks whether there is something that looks like a tag
-    before the first line break. Although the result may be correct
-    for common cases, there is no guarantee.
-
-    This function is defined in the \c <QTextDocument> header file.
-*/
 bool Qt::mightBeRichText(const QString& text)
 {
     if (text.isEmpty())
@@ -144,19 +131,6 @@ bool Qt::mightBeRichText(const QString& text)
     return false;
 }
 
-
-/*!
-    \fn QString Qt::convertFromPlainText(const QString &plain, Qt::WhiteSpaceMode mode)
-
-    Converts the plain text string \a plain to an HTML-formatted
-    paragraph while preserving most of its look.
-
-    \a mode defines how whitespace is handled.
-
-    This function is defined in the \c <QTextDocument> header file.
-
-    \sa escape(), mightBeRichText()
-*/
 QString Qt::convertFromPlainText(const QString &plain, Qt::WhiteSpaceMode mode)
 {
     int col = 0;
@@ -206,11 +180,6 @@ QString Qt::convertFromPlainText(const QString &plain, Qt::WhiteSpaceMode mode)
 }
 
 #ifndef QT_NO_TEXTCODEC
-/*!
-    \internal
-
-    This function is defined in the \c <QTextDocument> header file.
-*/
 QTextCodec *Qt::codecForHtml(const QByteArray &ba)
 {
     return QTextCodec::codecForHtml(ba);

src/gui/text/qtextdocument.h

@@ -70,6 +70,7 @@ class QTextCursor;
 
 template<typename T> class QVector;
 
+#ifndef Q_CLANG_QDOC
 namespace Qt
 {
     Q_GUI_EXPORT bool mightBeRichText(const QString&);
@@ -79,6 +80,7 @@ namespace Qt
     Q_GUI_EXPORT QTextCodec *codecForHtml(const QByteArray &ba);
 #endif
 }
+#endif
 
 class Q_GUI_EXPORT QAbstractUndoItem
 {

src/gui/text/qtextoption.cpp

@@ -165,7 +165,7 @@ void QTextOption::setTabArray(const QList<qreal> &tabStops)
     Sets the tab positions for the text layout to those specified by
     \a tabStops.
 
-    \sa tabStops()
+    \sa tabStop()
 */
 void QTextOption::setTabs(const QList<QTextOption::Tab> &tabStops)
 {

src/widgets/dialogs/qinputdialog.cpp

@@ -1312,7 +1312,7 @@ int QInputDialog::getInt(QWidget *parent, const QString &title, const QString &l
 }
 
 /*!
-    \fn QInputDialog::getInteger(QWidget *parent, const QString &title, const QString &label, int value, int min, int max, int step, bool *ok, Qt::WindowFlags flags)
+    \fn int QInputDialog::getInteger(QWidget *parent, const QString &title, const QString &label, int value, int min, int max, int step, bool *ok, Qt::WindowFlags flags)
     \deprecated use getInt()
 
     Static convenience function to get an integer input from the user.

src/widgets/graphicsview/qgraphicsitem.cpp

@@ -10640,7 +10640,7 @@ bool QGraphicsTextItemPrivate::_q_mouseOnEdge(QGraphicsSceneMouseEvent *event)
 }
 
 /*!
-    \fn QGraphicsTextItem::linkActivated(const QString &link)
+    \fn void QGraphicsTextItem::linkActivated(const QString &link)
 
     This signal is emitted when the user clicks on a link on a text item
     that enables Qt::LinksAccessibleByMouse or Qt::LinksAccessibleByKeyboard.
@@ -10650,7 +10650,7 @@ bool QGraphicsTextItemPrivate::_q_mouseOnEdge(QGraphicsSceneMouseEvent *event)
 */
 
 /*!
-    \fn QGraphicsTextItem::linkHovered(const QString &link)
+    \fn void QGraphicsTextItem::linkHovered(const QString &link)
 
     This signal is emitted when the user hovers over a link on a text item
     that enables Qt::LinksAccessibleByMouse. \a link is

src/widgets/graphicsview/qgraphicsscene.cpp

@@ -5521,7 +5521,7 @@ bool QGraphicsScene::focusNextPrevChild(bool next)
 */
 
 /*!
-    \fn QGraphicsScene::focusItemChanged(QGraphicsItem *newFocusItem, QGraphicsItem *oldFocusItem, Qt::FocusReason reason)
+    \fn void QGraphicsScene::focusItemChanged(QGraphicsItem *newFocusItem, QGraphicsItem *oldFocusItem, Qt::FocusReason reason)
 
     This signal is emitted by QGraphicsScene whenever focus changes in the
     scene (i.e., when an item gains or loses input focus, or when focus

src/widgets/graphicsview/qgraphicswidget_p.cpp

@@ -406,7 +406,7 @@ void QGraphicsWidgetPrivate::windowFrameMousePressEvent(QGraphicsSceneMouseEvent
     event->setAccepted(windowData->grabbedSection != Qt::NoSection);
 }
 
-/*!
+/*
   Used to calculate the
   Precondition:
   \a widget should support either hfw or wfh

src/widgets/itemviews/qlistwidget.cpp

@@ -1197,7 +1197,7 @@ void QListWidgetPrivate::_q_dataChanged(const QModelIndex &topLeft,
     new current item and the item that was previously current.
 
     \sa QListWidgetItem, QListView, QTreeView, {Model/View Programming},
-        {Config Dialog Example}
+        {Tab Dialog Example}
 */
 
 /*!

src/widgets/itemviews/qtreeview.cpp

@@ -4007,7 +4007,7 @@ int QTreeView::visualIndex(const QModelIndex &index) const
 }
 
 /*!
-   \reimp
+   \internal
 */
 
 void QTreeView::verticalScrollbarValueChanged(int value)

src/widgets/kernel/qgesturerecognizer.cpp

@@ -193,7 +193,7 @@ void QGestureRecognizer::reset(QGesture *gesture)
 }
 
 /*!
-    \fn QGestureRecognizer::recognize(QGesture *gesture, QObject *watched, QEvent *event)
+    \fn QGestureRecognizer::Result QGestureRecognizer::recognize(QGesture *gesture, QObject *watched, QEvent *event)
 
     Handles the given \a event for the \a watched object, updating the state of the \a gesture
     object as required, and returns a suitable result for the current recognition step.

src/widgets/util/qscroller.cpp

@@ -348,7 +348,7 @@ QObject *QScroller::target() const
 }
 
 /*!
-    \fn QScroller::scrollerPropertiesChanged(const QScrollerProperties &newProperties);
+    \fn void QScroller::scrollerPropertiesChanged(const QScrollerProperties &newProperties);
 
     QScroller emits this signal whenever its scroller properties change.
     \a newProperties are the new scroller properties.
@@ -518,7 +518,7 @@ QScroller::~QScroller()
 
 
 /*!
-    \fn QScroller::stateChanged(QScroller::State newState);
+    \fn void QScroller::stateChanged(QScroller::State newState);
 
     QScroller emits this signal whenever the state changes. \a newState is the new State.
 

src/widgets/widgets/qfontcombobox.cpp

@@ -524,7 +524,7 @@ void QFontComboBox::setCurrentFont(const QFont &font)
 }
 
 /*!
-    \fn QFontComboBox::currentFontChanged(const QFont &font)
+    \fn void QFontComboBox::currentFontChanged(const QFont &font)
 
     This signal is emitted whenever the current font changes, with
     the new \a font.

src/widgets/widgets/qlineedit.cpp

@@ -231,10 +231,10 @@ void QLineEdit::initStyleOption(QStyleOptionFrame *option) const
 */
 
 /*!
-    \fn void QLineEdit::cursorPositionChanged(int old, int new)
+    \fn void QLineEdit::cursorPositionChanged(int oldPos, int newPos)
 
     This signal is emitted whenever the cursor moves. The previous
-    position is given by \a old, and the new position by \a new.
+    position is given by \a oldPos, and the new position by \a newPos.
 
     \sa setCursorPosition(), cursorPosition()
 */

src/widgets/widgets/qmainwindow.cpp

@@ -951,7 +951,9 @@ void QMainWindow::setDockNestingEnabled(bool enabled)
 }
 
 #if 0
-/*! \property QMainWindow::verticalTabsEnabled
+// If added back in, add the '!' to the qdoc comment marker as well.
+/*
+    \property QMainWindow::verticalTabsEnabled
     \brief whether left and right dock areas use vertical tabs
     \since 4.2
 

src/widgets/widgets/qmdiarea.cpp

@@ -100,7 +100,7 @@
 */
 
 /*!
-    \fn QMdiArea::subWindowActivated(QMdiSubWindow *window)
+    \fn void QMdiArea::subWindowActivated(QMdiSubWindow *window)
 
     QMdiArea emits this signal after \a window has been activated. When \a
     window is 0, QMdiArea has just deactivated its last active window, and

src/widgets/widgets/qstackedwidget.cpp

@@ -101,7 +101,7 @@ public:
     widget is removed from the stacked widget, the currentChanged()
     and widgetRemoved() signals are emitted respectively.
 
-    \sa QStackedLayout, QTabWidget, {Config Dialog Example}
+    \sa QStackedLayout, QTabWidget
 */
 
 /*!

src/widgets/widgets/qstatusbar.cpp

@@ -601,7 +601,7 @@ QString QStatusBar::currentMessage() const
 }
 
 /*!
-    \fn QStatusBar::messageChanged(const QString &message)
+    \fn void QStatusBar::messageChanged(const QString &message)
 
     This signal is emitted whenever the temporary status message
     changes. The new temporary message is passed in the \a message