1berry/qtbase
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

qdoc: Fix several minor errors to reduce qdoc warnings

Browse Source 
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>
This commit is contained in:
Martin Smith 2018-08-10 12:14:05 +02:00
parent 30e26d258b
commit 109af99261
13 changed files with 71 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
src/corelib/doc/src/objectmodel/signalsandslots.qdoc
View File

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

4
src/corelib/global/qglobal.cpp
View File

@ -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:

41
src/gui/kernel/qplatformgraphicsbufferhelper.cpp
View File

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

2
src/network/ssl/qssl.h
View File

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

2
src/widgets/dialogs/qcolordialog.cpp
View File

@ -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.

6
src/widgets/dialogs/qinputdialog.cpp
View File

@ -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.

1
src/widgets/itemviews/qtreewidget.cpp
View File

@ -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.

7
src/widgets/widgets/qabstractspinbox.cpp
View File

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

8
src/widgets/widgets/qmenu.h
View File

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

3
src/widgets/widgets/qmenu_mac.mm
View File

@ -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.

6
src/widgets/widgets/qmenubar.h
View File

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

24
src/widgets/widgets/qspinbox.cpp
View File

@ -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);

4
src/xml/doc/src/xml-processing.qdoc
View File

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