summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorTopi Reinio <topi.reinio@qt.io>2019-11-11 22:45:22 +0100
committerTopi Reinio <topi.reinio@qt.io>2019-11-14 12:14:57 +0100
commit5d76ced033cf1b2a1466a1b1b2a3a4f1102fab3f (patch)
treebe508feadc8113d9aa1024764aa91587068a8df0
parent724c8d81b0ce39ffc32dfdcf1b134ac4befb0127 (diff)
downloadqtquickcontrols-5d76ced033cf1b2a1466a1b1b2a3a4f1102fab3f.tar.gz
Doc: Fix documentation warnings
All warnings in qtquickcontrols were related to \qmlmethod or \qmlsignal parameters, except for the missing dependency to qtcore in Qt Quick Extras. There's some inconsistencies with how QDoc parses QML method parameters, especially for qml signals - in some cases the \a command is replaced with \e to clear the warning, even though the parameter name referenced with \a does exist. This commit brings the current warning count to zero. Fixes: QTBUG-79828 Change-Id: I3d3d02583498c5a579f6476273e10e75680d940c Reviewed-by: Paul Wicking <paul.wicking@qt.io>
-rw-r--r--src/controls/Calendar.qml12
-rw-r--r--src/controls/ComboBox.qml2
-rw-r--r--src/controls/SplitView.qml2
-rw-r--r--src/controls/StackView.qml16
-rw-r--r--src/controls/StackViewDelegate.qml7
-rw-r--r--src/controls/Styles/Base/MenuBarStyle.qml6
-rw-r--r--src/controls/Styles/Base/MenuStyle.qml6
-rw-r--r--src/controls/TextArea.qml8
-rw-r--r--src/controls/TextField.qml2
-rw-r--r--src/controls/doc/src/qtquickcontrols-tableview.qdoc4
-rw-r--r--src/controls/doc/src/qtquickcontrols-treeview.qdoc8
-rw-r--r--src/controls/qquickaction.cpp16
-rw-r--r--src/controls/qquickexclusivegroup.cpp8
-rw-r--r--src/controls/qquickmenu.cpp16
-rw-r--r--src/controls/qquickmenuitem.cpp4
-rw-r--r--src/extras/PieMenu.qml2
-rw-r--r--src/extras/Tumbler.qml2
-rw-r--r--src/extras/doc/qtquickextras.qdocconf2
18 files changed, 65 insertions, 58 deletions
diff --git a/src/controls/Calendar.qml b/src/controls/Calendar.qml
index 3a225744..bf3d6737 100644
--- a/src/controls/Calendar.qml
+++ b/src/controls/Calendar.qml
@@ -244,7 +244,7 @@ Control {
Emitted when the mouse hovers over a valid date in the calendar.
- \a date is the date that was hovered over.
+ \e date is the date that was hovered over.
The corresponding handler is \c onHovered.
*/
@@ -257,7 +257,7 @@ Control {
This is also emitted when dragging the mouse to another date while it is pressed.
- \a date is the date that the mouse was pressed on.
+ \e date is the date that the mouse was pressed on.
The corresponding handler is \c onPressed.
*/
@@ -268,7 +268,7 @@ Control {
Emitted when the mouse is released over a valid date in the calendar.
- \a date is the date that the mouse was released over.
+ \e date is the date that the mouse was released over.
The corresponding handler is \c onReleased.
*/
@@ -279,7 +279,7 @@ Control {
Emitted when the mouse is clicked on a valid date in the calendar.
- \a date is the date that the mouse was clicked on.
+ \e date is the date that the mouse was clicked on.
The corresponding handler is \c onClicked.
*/
@@ -290,7 +290,7 @@ Control {
Emitted when the mouse is double-clicked on a valid date in the calendar.
- \a date is the date that the mouse was double-clicked on.
+ \e date is the date that the mouse was double-clicked on.
The corresponding handler is \c onDoubleClicked.
*/
@@ -302,7 +302,7 @@ Control {
Emitted when the mouse is pressed and held on a valid date in the calendar.
- \a date is the date that the mouse was pressed on.
+ \e date is the date that the mouse was pressed on.
The corresponding handler is \c onPressAndHold.
*/
diff --git a/src/controls/ComboBox.qml b/src/controls/ComboBox.qml
index 94bbc0cd..b01cfe12 100644
--- a/src/controls/ComboBox.qml
+++ b/src/controls/ComboBox.qml
@@ -341,7 +341,7 @@ Control {
be emitted if the combo box index was changed by the user, not
when set programmatically.
- \a index is the activated model index, or \c -1 if a new string is
+ \e index is the activated model index, or \c -1 if a new string is
accepted.
The corresponding handler is \c onActivated.
diff --git a/src/controls/SplitView.qml b/src/controls/SplitView.qml
index b95704d3..471e70a0 100644
--- a/src/controls/SplitView.qml
+++ b/src/controls/SplitView.qml
@@ -186,7 +186,7 @@ Item {
onOrientationChanged: d.changeOrientation()
/*! \qmlmethod void SplitView::addItem(Item item)
- Add an item to the end of the view.
+ Add an \a item to the end of the view.
\since QtQuick.Controls 1.3 */
function addItem(item) {
d.updateLayoutGuard = true
diff --git a/src/controls/StackView.qml b/src/controls/StackView.qml
index aa3596f3..290d24c2 100644
--- a/src/controls/StackView.qml
+++ b/src/controls/StackView.qml
@@ -515,24 +515,24 @@ FocusScope {
property StackViewDelegate delegate: StackViewSlideDelegate {}
/*! \qmlmethod Item StackView::push(Item item)
- Pushes an item onto the stack.
+ Pushes an \a item onto the stack.
The function can also take a property list as argument - \c {Item StackView::push(jsobject dict)}, which
should contain one or more of the following properties:
\list
- \li \c item: this property is required, and holds the item you want to push.
- \li \c properties: a list of QML properties that should be assigned
+ \li \a item: this property is required, and holds the item you want to push.
+ \li \e properties: a list of QML properties that should be assigned
to the item upon push. These properties will be copied into the item when it is
loaded (in case of a component or URL), or when it becomes the current item for the
first time (normally upon push).
- \li \c immediate: set this property to \c true to skip transition effects. When pushing
+ \li \e immediate: set this property to \c true to skip transition effects. When pushing
an array, you only need to set this property on the first element to make the
whole operation immediate.
- \li \c replace: set this property to replace the current item on the stack. When pushing
+ \li \e replace: set this property to replace the current item on the stack. When pushing
an array, you only need to set this property on the first element to replace
as many elements on the stack as inside the array.
- \li \c destroyOnPop: set this property to specify if the item needs to be destroyed
- when its popped off the stack. By default (if \a destroyOnPop is not specified),
+ \li \e destroyOnPop: set this property to specify if the item needs to be destroyed
+ when its popped off the stack. By default (if \e destroyOnPop is not specified),
StackView will destroy items pushed as components or URLs. Items
not destroyed will be re-parented to the original parents they had before being
pushed onto the stack, and hidden. If you need to set this property, do it with
@@ -700,7 +700,7 @@ FocusScope {
}
/*! \qmlmethod Item StackView::find(function, bool onlySearchLoadedItems = false)
- Search for a specific item inside the stack. \a func will
+ Search for a specific item inside the stack. \a function will
be called for each item in the stack (with the item as argument)
until the function returns true. Return value will be the item found. For
example:
diff --git a/src/controls/StackViewDelegate.qml b/src/controls/StackViewDelegate.qml
index 23a9ee69..f85eb0ae 100644
--- a/src/controls/StackViewDelegate.qml
+++ b/src/controls/StackViewDelegate.qml
@@ -56,7 +56,8 @@ QtObject {
/*!
\qmlmethod Transition StackViewDelegate::getTransition(properties)
- The base implementation of this function just looks for a property named properties.name inside itself.
+ The base implementation of this function just looks for a property named
+ \a {properties}.name inside itself and returns it.
\sa {Transitions}
*/
function getTransition(properties)
@@ -67,7 +68,9 @@ QtObject {
/*!
\qmlmethod void StackViewDelegate::transitionFinished(properties)
- The base implementation of this function is empty.
+ Handles the completion of a transition for \a properties. The base
+ implementation of this function is empty.
+
\sa {Transitions}
*/
function transitionFinished(properties)
diff --git a/src/controls/Styles/Base/MenuBarStyle.qml b/src/controls/Styles/Base/MenuBarStyle.qml
index 5992d981..ade34b0a 100644
--- a/src/controls/Styles/Base/MenuBarStyle.qml
+++ b/src/controls/Styles/Base/MenuBarStyle.qml
@@ -57,13 +57,13 @@ Style {
/*!
\qmlmethod string MenuBarStyle::formatMnemonic(string text, bool underline = false)
- Returns a formatted string to render mnemonics for a given menu item.
+ Returns a formatted string to render mnemonics for a given menu item \a text.
The mnemonic character is prefixed by an ampersand in the original string.
- Passing \c true for \c underline will underline the mnemonic character (e.g.,
+ Passing \c true for \e underline will underline the mnemonic character (e.g.,
\c formatMnemonic("&File", true) will return \c "<u>F</u>ile"). Passing \c false
- for \c underline will return the plain text form (e.g., \c formatMnemonic("&File", false)
+ for \a underline will return the plain text form (e.g., \c formatMnemonic("&File", false)
will return \c "File").
\sa Label
diff --git a/src/controls/Styles/Base/MenuStyle.qml b/src/controls/Styles/Base/MenuStyle.qml
index 13a889c4..f40e0af7 100644
--- a/src/controls/Styles/Base/MenuStyle.qml
+++ b/src/controls/Styles/Base/MenuStyle.qml
@@ -98,13 +98,13 @@ Style {
/*!
\qmlmethod string MenuStyle::formatMnemonic(string text, bool underline = false)
- Returns a rich-text string to render mnemonics for a given menu item.
+ Returns a rich-text string to render mnemonics for a given menu item \a text.
The mnemonic character is prefixed by an ampersand in the original string.
- Passing \c true for \c underline will underline the mnemonic character (e.g.,
+ Passing \c true for \a underline will underline the mnemonic character (e.g.,
\c formatMnemonic("&Open...", true) will return \c "<u>O</u>pen..."). Passing \c false
- for \c underline will return the plain text form (e.g., \c formatMnemonic("&Open...", false)
+ for \a underline will return the plain text form (e.g., \c formatMnemonic("&Open...", false)
will return \c "Open...").
\sa Label
diff --git a/src/controls/TextArea.qml b/src/controls/TextArea.qml
index 89877314..ac6ecac3 100644
--- a/src/controls/TextArea.qml
+++ b/src/controls/TextArea.qml
@@ -405,7 +405,7 @@ ScrollView {
This signal is emitted when the user clicks on a link embedded in the text.
The link must be in rich text or HTML format and the
- \a link string provides access to the particular link.
+ \e link string provides access to the particular link.
The corresponding handler is \c onLinkActivated.
*/
@@ -417,7 +417,7 @@ ScrollView {
This signal is emitted when the user hovers a link embedded in the text.
The link must be in rich text or HTML format and the
- \a link string provides access to the particular link.
+ \e link string provides access to the particular link.
\sa hoveredLink
@@ -459,7 +459,7 @@ ScrollView {
/*!
\qmlmethod void TextArea::append(string text)
- Appends \a string as a new line to the end of the text area.
+ Appends a string \a text as a new line to the end of the text area.
*/
function append (string) {
edit.append(string)
@@ -518,7 +518,7 @@ ScrollView {
/*!
\qmlmethod void TextArea::insert(int position, string text)
- Inserts \a text into the TextArea at position.
+ Inserts \a text into the TextArea at \a position.
*/
function insert(position, text) {
edit.insert(position, text);
diff --git a/src/controls/TextField.qml b/src/controls/TextField.qml
index d6b9b9c9..d0d1d5cc 100644
--- a/src/controls/TextField.qml
+++ b/src/controls/TextField.qml
@@ -547,7 +547,7 @@ Control {
\qmlmethod void TextField::remove(int start, int end)
\since QtQuick.Controls 1.4
- Removes the section of text that is between the start and end positions.
+ Removes the section of text that is between the \a start and \a end positions.
*/
function remove(start, end) {
textInput.remove(start, end)
diff --git a/src/controls/doc/src/qtquickcontrols-tableview.qdoc b/src/controls/doc/src/qtquickcontrols-tableview.qdoc
index 99b1202e..e118e9f6 100644
--- a/src/controls/doc/src/qtquickcontrols-tableview.qdoc
+++ b/src/controls/doc/src/qtquickcontrols-tableview.qdoc
@@ -179,7 +179,7 @@
/*!
\qmlmethod void TableView::positionViewAtRow( int row, PositionMode mode )
- Positions the view such that the specified \a row is at the position defined by \a mode:
+ Positions the view such that the specified \a row is at the position defined by \e mode:
\list
\li ListView.Beginning - position item at the top of the view.
\li ListView.Center - position item in the center of the view.
@@ -208,7 +208,7 @@
/*!
\qmlmethod int TableView::rowAt( int x, int y )
- Returns the index of the visible row at the point \a x, \a y in content
+ Returns the index of the visible row at the point \a x, \e y in content
coordinates. If there is no visible row at the point specified, \c -1 is returned.
\note This method should only be called after the component has completed.
diff --git a/src/controls/doc/src/qtquickcontrols-treeview.qdoc b/src/controls/doc/src/qtquickcontrols-treeview.qdoc
index 438eec7a..6542a939 100644
--- a/src/controls/doc/src/qtquickcontrols-treeview.qdoc
+++ b/src/controls/doc/src/qtquickcontrols-treeview.qdoc
@@ -265,7 +265,7 @@
/*!
\qmlmethod bool TreeView::isExpanded(QModelIndex index)
- Returns true if the model item index is expanded; otherwise returns false.
+ Returns true if the model item at \a index is expanded; otherwise returns false.
\sa {expanded}, {expand}
*/
@@ -273,7 +273,7 @@
/*!
\qmlmethod void TreeView::collapse(QModelIndex index)
- Collapses the model item specified by the index.
+ Collapses the model item specified by the \a index.
\sa {collapsed}, {isExpanded}
*/
@@ -281,7 +281,7 @@
/*!
\qmlmethod void TreeView::expand(QModelIndex index)
- Expands the model item specified by the index.
+ Expands the model item specified by the \a index.
\sa {expanded}, {isExpanded}
*/
@@ -289,7 +289,7 @@
/*!
\qmlmethod QModelIndex TreeView::indexAt( int x, int y )
- Returns the model index of the visible row at the point \a x, \a y in content
+ Returns the model index of the visible row at the point \a x, \e y in content
coordinates. If there is no visible row at the point specified, an invalid
\l QModelIndex is returned.
diff --git a/src/controls/qquickaction.cpp b/src/controls/qquickaction.cpp
index 27fd3377..479bb7fb 100644
--- a/src/controls/qquickaction.cpp
+++ b/src/controls/qquickaction.cpp
@@ -169,28 +169,30 @@ QT_BEGIN_NAMESPACE
\endqml
*/
-/*! \qmlsignal Action::triggered(QObject *source)
+/*! \qmlsignal Action::triggered(QtObject source)
Emitted when either the menu item or its bound action have been activated. Includes
- the object that triggered the event if relevant (e.g. a Button or MenuItem).
+ the object (\a source) that triggered the event if relevant (e.g. a Button or MenuItem).
You shouldn't need to emit this signal, use \l trigger() instead.
The corresponding handler is \c onTriggered.
*/
-/*! \qmlmethod void Action::trigger(QObject *source)
+/*! \qmlmethod void Action::trigger(QtObject source)
- Will emit the \l triggered signal if the action is enabled. You may provide a source
- object if the Action would benefit from knowing the origin of the triggering (e.g.
- for analytics). Will also emit the \l toggled signal if it is checkable.
+ Will emit the \l triggered signal on \a source if the action is enabled. You may provide
+ a source object if the Action would benefit from knowing the origin of the triggering
+ (e.g. for analytics). Will also emit the \l toggled signal if it is checkable.
*/
/*! \qmlsignal Action::toggled(checked)
- Emitted whenever a action's \l checked property changes.
+ Emitted whenever an action's \a checked property changes.
This usually happens at the same time as \l triggered.
The corresponding handler is \c onToggled.
+
+ \sa checked
*/
QQuickAction1::QQuickAction1(QObject *parent)
diff --git a/src/controls/qquickexclusivegroup.cpp b/src/controls/qquickexclusivegroup.cpp
index 14f17585..c613e943 100644
--- a/src/controls/qquickexclusivegroup.cpp
+++ b/src/controls/qquickexclusivegroup.cpp
@@ -158,9 +158,9 @@ static bool isChecked(const QObject *o)
/*!
\qmlmethod void ExclusiveGroup::bindCheckable(object)
- Register \c object to the exclusive group.
+ Registers \a object to the exclusive group.
- You should only need to call this function when creating a component you want to be compatible with \c ExclusiveGroup.
+ You should only need to call this function when creating a component you want to be compatible with ExclusiveGroup.
\sa ExclusiveGroup::unbindCheckable()
*/
@@ -168,9 +168,9 @@ static bool isChecked(const QObject *o)
/*!
\qmlmethod void ExclusiveGroup::unbindCheckable(object)
- Unregister \c object from the exclusive group.
+ Unregisters \a object from the exclusive group.
- You should only need to call this function when creating a component you want to be compatible with \c ExclusiveGroup.
+ You should only need to call this function when creating a component you want to be compatible with ExclusiveGroup.
\sa ExclusiveGroup::bindCheckable()
*/
diff --git a/src/controls/qquickmenu.cpp b/src/controls/qquickmenu.cpp
index bfa0f673..bbbbe97c 100644
--- a/src/controls/qquickmenu.cpp
+++ b/src/controls/qquickmenu.cpp
@@ -174,7 +174,7 @@ QT_BEGIN_NAMESPACE
/*!
\qmlmethod MenuItem Menu::addItem(string text)
- Adds an item to the menu. Returns the newly created \l MenuItem.
+ Adds a \a text item to the menu. Returns the newly created \l MenuItem.
\sa insertItem()
*/
@@ -182,7 +182,7 @@ QT_BEGIN_NAMESPACE
/*!
\qmlmethod MenuItem Menu::insertItem(int before, string title)
- Creates and inserts an item with title \c title at the index \c before in the current menu.
+ Creates and inserts an item with title \a title at the index \a before in the current menu.
Returns the newly created \l MenuItem.
\sa addItem()
@@ -199,14 +199,14 @@ QT_BEGIN_NAMESPACE
/*!
\qmlmethod void Menu::insertSeparator(int before)
- Creates and inserts a separator at the index \c before in the current menu.
+ Creates and inserts a separator at the index \a before in the current menu.
\sa addSeparator()
*/
/*!
\qmlmethod Menu Menu::addMenu(string title)
- Adds a submenu to the menu. Returns the newly created \l Menu.
+ Adds a submenu with a title \a title to the menu. Returns the newly created \l Menu.
\sa insertMenu()
*/
@@ -214,7 +214,7 @@ QT_BEGIN_NAMESPACE
/*!
\qmlmethod MenuItem Menu::insertMenu(int before, string title)
- Creates and inserts a submenu with title \c title at the index \c before in the current menu.
+ Creates and inserts a submenu with a title \a title at the index \a before in the current menu.
Returns the newly created \l Menu.
\sa addMenu()
@@ -223,7 +223,7 @@ QT_BEGIN_NAMESPACE
/*!
\qmlmethod void Menu::insertItem(int before, object item)
- Inserts the \c item at the index \c before in the current menu.
+ Inserts the \a item at the index \a before in the current menu.
In this case, \c item can be either a \l MenuItem, a \l MenuSeparator,
or a \l Menu.
@@ -233,8 +233,8 @@ QT_BEGIN_NAMESPACE
/*!
\qmlmethod void Menu::removeItem(item)
- Removes the \c item from the menu.
- In this case, \c item can be either a \l MenuItem, a \l MenuSeparator,
+ Removes the \a item from the menu.
+ In this case, \a item can be either a \l MenuItem, a \l MenuSeparator,
or a \l Menu.
\sa insertItem()
diff --git a/src/controls/qquickmenuitem.cpp b/src/controls/qquickmenuitem.cpp
index 60aa0f6f..6ed9c4f1 100644
--- a/src/controls/qquickmenuitem.cpp
+++ b/src/controls/qquickmenuitem.cpp
@@ -440,12 +440,14 @@ void QQuickMenuText1::updateIcon()
/*! \qmlsignal MenuItem::toggled(checked)
- Emitted whenever a menu item's \c checked property changes.
+ Emitted whenever a menu item's \a checked property changes.
This usually happens at the same time as \l triggered.
\sa checked, triggered, Action::triggered, Action::toggled
The corresponding handler is \c onToggled.
+
+ \sa checked
*/
/*!
diff --git a/src/extras/PieMenu.qml b/src/extras/PieMenu.qml
index d339795a..cfaaecbe 100644
--- a/src/extras/PieMenu.qml
+++ b/src/extras/PieMenu.qml
@@ -332,7 +332,7 @@ Control {
/*!
\qmlmethod void addItem(string text)
- Adds an item to the end of the menu items.
+ Adds a \a text item to the end of the menu items.
Equivalent to passing calling \c insertItem(menuItems.length, text).
diff --git a/src/extras/Tumbler.qml b/src/extras/Tumbler.qml
index a6208708..fe1dfed1 100644
--- a/src/extras/Tumbler.qml
+++ b/src/extras/Tumbler.qml
@@ -171,7 +171,7 @@ Control {
/*!
\qmlmethod int Tumbler::currentIndexAt(int columnIndex)
Returns the current index of the column at \a columnIndex, or \c null
- if the \a index is invalid.
+ if \a columnIndex is invalid.
*/
function currentIndexAt(columnIndex) {
if (!__isValidColumnIndex(columnIndex))
diff --git a/src/extras/doc/qtquickextras.qdocconf b/src/extras/doc/qtquickextras.qdocconf
index 7a82854c..9299bc98 100644
--- a/src/extras/doc/qtquickextras.qdocconf
+++ b/src/extras/doc/qtquickextras.qdocconf
@@ -28,7 +28,7 @@ qhp.QtQuickExtras.subprojects.qtquickextrasexamples.indexTitle = Qt Quick Extras
qhp.QtQuickExtras.subprojects.qtquickextrasexamples.selectors = fake:example
qhp.QtQuickExtras.subprojects.qtquickextrasexamples.sortPages = true
-depends = qtqml qtquick qtdoc qtquickcontrols1 qtgui
+depends = qtcore qtqml qtquick qtdoc qtquickcontrols1 qtgui
exampledirs += ../../../examples/quickcontrols/extras
examplesinstallpath = quickcontrols/extras