From 43fbf30efaffca2b95625f5b04429e5fc31bc770 Mon Sep 17 00:00:00 2001 From: Martin Smith Date: Thu, 18 Jan 2018 11:40:43 +0100 Subject: doc: Fix many qdoc warnings, mostly missing return types MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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ö --- src/corelib/global/qnamespace.h | 10 ++++++++ src/corelib/global/qnamespace.qdoc | 34 ++++++++++++++++++++++++++ src/gui/kernel/qcursor.cpp | 6 +++++ src/gui/opengl/qopenglfunctions.h | 2 ++ src/gui/text/qtextdocument.cpp | 31 ----------------------- src/gui/text/qtextdocument.h | 2 ++ src/gui/text/qtextoption.cpp | 2 +- src/widgets/dialogs/qinputdialog.cpp | 2 +- src/widgets/graphicsview/qgraphicsitem.cpp | 4 +-- src/widgets/graphicsview/qgraphicsscene.cpp | 2 +- src/widgets/graphicsview/qgraphicswidget_p.cpp | 2 +- src/widgets/itemviews/qlistwidget.cpp | 2 +- src/widgets/itemviews/qtreeview.cpp | 2 +- src/widgets/kernel/qgesturerecognizer.cpp | 2 +- src/widgets/util/qscroller.cpp | 4 +-- src/widgets/widgets/qfontcombobox.cpp | 2 +- src/widgets/widgets/qlineedit.cpp | 4 +-- src/widgets/widgets/qmainwindow.cpp | 4 ++- src/widgets/widgets/qmdiarea.cpp | 2 +- src/widgets/widgets/qstackedwidget.cpp | 2 +- src/widgets/widgets/qstatusbar.cpp | 2 +- 21 files changed, 74 insertions(+), 49 deletions(-) diff --git a/src/corelib/global/qnamespace.h b/src/corelib/global/qnamespace.h index 05383d00b6..fb40c71f7a 100644 --- a/src/corelib/global/qnamespace.h +++ b/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 diff --git a/src/corelib/global/qnamespace.qdoc b/src/corelib/global/qnamespace.qdoc index 2614a0bfd9..dd0b18dfa0 100644 --- a/src/corelib/global/qnamespace.qdoc +++ b/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 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 header file. + + \sa escape(), mightBeRichText() +*/ + +/*! + \fn QTextCodec *Qt::codecForHtml(const QByteArray &ba) + \internal + + This function is defined in the \c header file. +*/ diff --git a/src/gui/kernel/qcursor.cpp b/src/gui/kernel/qcursor.cpp index 8ae9085d9f..bb81ca109a 100644 --- a/src/gui/kernel/qcursor.cpp +++ b/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) diff --git a/src/gui/opengl/qopenglfunctions.h b/src/gui/opengl/qopenglfunctions.h index 72af128219..1a43f13d9b 100644 --- a/src/gui/opengl/qopenglfunctions.h +++ b/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 diff --git a/src/gui/text/qtextdocument.cpp b/src/gui/text/qtextdocument.cpp index 931c9d7490..d95932f4db 100644 --- a/src/gui/text/qtextdocument.cpp +++ b/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 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 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 header file. -*/ QTextCodec *Qt::codecForHtml(const QByteArray &ba) { return QTextCodec::codecForHtml(ba); diff --git a/src/gui/text/qtextdocument.h b/src/gui/text/qtextdocument.h index 41c578fc1b..c847d3ce88 100644 --- a/src/gui/text/qtextdocument.h +++ b/src/gui/text/qtextdocument.h @@ -70,6 +70,7 @@ class QTextCursor; template 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 { diff --git a/src/gui/text/qtextoption.cpp b/src/gui/text/qtextoption.cpp index 310ced5463..a3fa0e7351 100644 --- a/src/gui/text/qtextoption.cpp +++ b/src/gui/text/qtextoption.cpp @@ -165,7 +165,7 @@ void QTextOption::setTabArray(const QList &tabStops) Sets the tab positions for the text layout to those specified by \a tabStops. - \sa tabStops() + \sa tabStop() */ void QTextOption::setTabs(const QList &tabStops) { diff --git a/src/widgets/dialogs/qinputdialog.cpp b/src/widgets/dialogs/qinputdialog.cpp index b9bf25f99c..5c6e0f45a5 100644 --- a/src/widgets/dialogs/qinputdialog.cpp +++ b/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. diff --git a/src/widgets/graphicsview/qgraphicsitem.cpp b/src/widgets/graphicsview/qgraphicsitem.cpp index f298ffd61e..0bc3af2f77 100644 --- a/src/widgets/graphicsview/qgraphicsitem.cpp +++ b/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 diff --git a/src/widgets/graphicsview/qgraphicsscene.cpp b/src/widgets/graphicsview/qgraphicsscene.cpp index 8b088e7c01..25b77aa02f 100644 --- a/src/widgets/graphicsview/qgraphicsscene.cpp +++ b/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 diff --git a/src/widgets/graphicsview/qgraphicswidget_p.cpp b/src/widgets/graphicsview/qgraphicswidget_p.cpp index c913e210b9..1514fca456 100644 --- a/src/widgets/graphicsview/qgraphicswidget_p.cpp +++ b/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 diff --git a/src/widgets/itemviews/qlistwidget.cpp b/src/widgets/itemviews/qlistwidget.cpp index 2cca3cbb3a..ad8aac1415 100644 --- a/src/widgets/itemviews/qlistwidget.cpp +++ b/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} */ /*! diff --git a/src/widgets/itemviews/qtreeview.cpp b/src/widgets/itemviews/qtreeview.cpp index bb0c26fc77..9b7797993c 100644 --- a/src/widgets/itemviews/qtreeview.cpp +++ b/src/widgets/itemviews/qtreeview.cpp @@ -4007,7 +4007,7 @@ int QTreeView::visualIndex(const QModelIndex &index) const } /*! - \reimp + \internal */ void QTreeView::verticalScrollbarValueChanged(int value) diff --git a/src/widgets/kernel/qgesturerecognizer.cpp b/src/widgets/kernel/qgesturerecognizer.cpp index e7873d455e..65c46a5e56 100644 --- a/src/widgets/kernel/qgesturerecognizer.cpp +++ b/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. diff --git a/src/widgets/util/qscroller.cpp b/src/widgets/util/qscroller.cpp index 4f5cf55a64..903a141e49 100644 --- a/src/widgets/util/qscroller.cpp +++ b/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. diff --git a/src/widgets/widgets/qfontcombobox.cpp b/src/widgets/widgets/qfontcombobox.cpp index 1d0e7cfd68..957a464b71 100644 --- a/src/widgets/widgets/qfontcombobox.cpp +++ b/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. diff --git a/src/widgets/widgets/qlineedit.cpp b/src/widgets/widgets/qlineedit.cpp index 94f13c6984..156b0e331c 100644 --- a/src/widgets/widgets/qlineedit.cpp +++ b/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() */ diff --git a/src/widgets/widgets/qmainwindow.cpp b/src/widgets/widgets/qmainwindow.cpp index 00ee0a9d10..bf0a88e7fb 100644 --- a/src/widgets/widgets/qmainwindow.cpp +++ b/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 diff --git a/src/widgets/widgets/qmdiarea.cpp b/src/widgets/widgets/qmdiarea.cpp index ff3e9d2d3b..45c01dec80 100644 --- a/src/widgets/widgets/qmdiarea.cpp +++ b/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 diff --git a/src/widgets/widgets/qstackedwidget.cpp b/src/widgets/widgets/qstackedwidget.cpp index 9d92855a40..2217dab870 100644 --- a/src/widgets/widgets/qstackedwidget.cpp +++ b/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 */ /*! diff --git a/src/widgets/widgets/qstatusbar.cpp b/src/widgets/widgets/qstatusbar.cpp index 4635b73a81..fb551158bf 100644 --- a/src/widgets/widgets/qstatusbar.cpp +++ b/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 -- cgit v1.2.3