Doc: Improve imperative Menu API documentationHEADdev

This commit adds links to the topic about creating menu items, because
this proccess is not straightforward. The commit clarifies the
ownership of newly added menu items, sub menus, and actions.

Fixes: QTBUG-134936
Pick-to: 6.10 6.9 6.8
Change-Id: Iea8fb74a759fcb4e0558aadba3cf0a22892f35f0
Reviewed-by: Mitch Curtis <[email protected]>

1 files changed, 19 insertions, 7 deletions

diff --git a/src/quicktemplates/qquickmenu.cpp b/src/quicktemplates/qquickmenu.cpp
index 727af3772b..43cbb7ba8d 100644
--- a/src/quicktemplates/qquickmenu.cpp
+++ b/src/quicktemplates/qquickmenu.cpp
@@ -1396,7 +1396,10 @@ QQuickItem *QQuickMenu::itemAt(int index) const
 /*!
     \qmlmethod void QtQuick.Controls::Menu::addItem(Item item)
 
-    Adds \a item to the end of the list of items.
+    Adds \a item to the end of the list of items. The menu does not take
+    ownership of the newly added \a item.
+
+    \sa {Dynamically Generating Menu Items}
 */
 void QQuickMenu::addItem(QQuickItem *item)
 {
@@ -1407,7 +1410,10 @@ void QQuickMenu::addItem(QQuickItem *item)
 /*!
     \qmlmethod void QtQuick.Controls::Menu::insertItem(int index, Item item)
 
-    Inserts \a item at \a index.
+    Inserts \a item at \a index. The menu does not take ownership of the newly
+    inserted \a item.
+
+    \sa {Dynamically Generating Menu Items}
 */
 void QQuickMenu::insertItem(int index, QQuickItem *item)
 {
@@ -1509,7 +1515,8 @@ QQuickMenu *QQuickMenu::menuAt(int index) const
     \since QtQuick.Controls 2.3 (Qt 5.10)
     \qmlmethod void QtQuick.Controls::Menu::addMenu(Menu menu)
 
-    Adds \a menu as a sub-menu to the end of this menu.
+    Adds \a menu as a sub-menu to the end of this menu. The menu does not take
+    ownership of the newly added \a menu.
 */
 void QQuickMenu::addMenu(QQuickMenu *menu)
 {
@@ -1521,7 +1528,8 @@ void QQuickMenu::addMenu(QQuickMenu *menu)
     \since QtQuick.Controls 2.3 (Qt 5.10)
     \qmlmethod void QtQuick.Controls::Menu::insertMenu(int index, Menu menu)
 
-    Inserts \a menu as a sub-menu at \a index. The index is within all items in the menu.
+    Inserts \a menu as a sub-menu at \a index. The index is within all items in
+    the menu. The menu does not take ownership of the newly inserted \a menu.
 */
 void QQuickMenu::insertMenu(int index, QQuickMenu *menu)
 {
@@ -1561,7 +1569,8 @@ void QQuickMenu::removeMenu(QQuickMenu *menu)
     \since QtQuick.Controls 2.3 (Qt 5.10)
     \qmlmethod Menu QtQuick.Controls::Menu::takeMenu(int index)
 
-    Removes and returns the menu at \a index. The index is within all items in the menu.
+    Removes and returns the menu at \a index. The index is within all items in
+    the menu.
 
     \note The ownership of the menu is transferred to the caller.
 */
@@ -1610,7 +1619,8 @@ QQuickAction *QQuickMenu::actionAt(int index) const
     \since QtQuick.Controls 2.3 (Qt 5.10)
     \qmlmethod void QtQuick.Controls::Menu::addAction(Action action)
 
-    Adds \a action to the end of this menu.
+    Adds \a action to the end of this menu. The menu does not take ownership of
+    the newly added \a action.
 */
 void QQuickMenu::addAction(QQuickAction *action)
 {
@@ -1623,6 +1633,7 @@ void QQuickMenu::addAction(QQuickAction *action)
     \qmlmethod void QtQuick.Controls::Menu::insertAction(int index, Action action)
 
     Inserts \a action at \a index. The index is within all items in the menu.
+    The menu does not take ownership of the newly inserted \a action.
 */
 void QQuickMenu::insertAction(int index, QQuickAction *action)
 {
@@ -1662,7 +1673,8 @@ void QQuickMenu::removeAction(QQuickAction *action)
     \since QtQuick.Controls 2.3 (Qt 5.10)
     \qmlmethod Action QtQuick.Controls::Menu::takeAction(int index)
 
-    Removes and returns the action at \a index. The index is within all items in the menu.
+    Removes and returns the action at \a index. The index is within all items in
+    the menu.
 
     \note The ownership of the action is transferred to the caller.
 */