From 60298245da4a9fcfe4479d18c80cb29a1ce5b603 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Tue, 16 Apr 2019 11:24:24 +1200 Subject: [PATCH 1/2] Menu JSDoc update --- .../src/scripting/MenuScriptingInterface.h | 93 +++++++++---------- .../script-engine/src/MenuItemProperties.cpp | 22 ++--- 2 files changed, 56 insertions(+), 59 deletions(-) diff --git a/interface/src/scripting/MenuScriptingInterface.h b/interface/src/scripting/MenuScriptingInterface.h index 02d5c84138..1ab691ac59 100644 --- a/interface/src/scripting/MenuScriptingInterface.h +++ b/interface/src/scripting/MenuScriptingInterface.h @@ -18,18 +18,15 @@ class MenuItemProperties; /**jsdoc - * The Menu API provides access to the menu that is displayed at the top of the window - * on a user's desktop and in the tablet when the "MENU" button is pressed. - * - *

+ * The Menu API provides access to the menu that is displayed at the top of the window on a user's desktop and in + * the tablet when the "MENU" button is pressed. * *

Groupings

* - * A "grouping" provides a way to group a set of menus or menu items together so - * that they can all be set visible or invisible as a group. - * There are two available groups: "Advanced" and "Developer". - * These groupings can be toggled in the "Settings" menu. - * If a menu item doesn't belong to a group it is always displayed. + *

A "grouping" provides a way to group a set of menus or menu items together so that they can all be set visible or invisible + * as a group.

There is currently only one available group: "Developer". This grouping can be toggled in the + * "Settings" menu.

+ *

If a menu item doesn't belong to a group it is always displayed.

* * @namespace Menu * @@ -60,22 +57,23 @@ private slots: public slots: /**jsdoc - * Add a new top-level menu. + * Adds a new top-level menu. * @function Menu.addMenu - * @param {string} menuName - Name that will be displayed for the menu. Nested menus can be described using the ">" symbol. + * @param {string} menuName - Name that will be displayed for the menu. Nested menus can be specified using the + * ">" character. * @param {string} [grouping] - Name of the grouping, if any, to add this menu to. * * @example Add a menu and a nested submenu. * Menu.addMenu("Test Menu"); * Menu.addMenu("Test Menu > Test Sub Menu"); * - * @example Add a menu to the Settings menu that is only visible if Settings > Advanced is enabled. - * Menu.addMenu("Settings > Test Grouping Menu", "Advanced"); + * @example Add a menu to the Settings menu that is only visible if Settings > Developer is enabled. + * Menu.addMenu("Settings > Test Grouping Menu", "Developer"); */ void addMenu(const QString& menuName, const QString& grouping = QString()); /**jsdoc - * Remove a top-level menu. + * Removes a top-level menu. * @function Menu.removeMenu * @param {string} menuName - Name of the menu to remove. * @example Remove a menu and nested submenu. @@ -85,7 +83,7 @@ public slots: void removeMenu(const QString& menuName); /**jsdoc - * Check whether a top-level menu exists. + * Checks whether a top-level menu exists. * @function Menu.menuExists * @param {string} menuName - Name of the menu to check for existence. * @returns {boolean} true if the menu exists, otherwise false. @@ -97,45 +95,44 @@ public slots: bool menuExists(const QString& menuName); /**jsdoc - * Add a separator with an unclickable label below it. The separator will be placed at the bottom of the menu. - * If you want to add a separator at a specific point in the menu, use {@link Menu.addMenuItem} with - * {@link Menu.MenuItemProperties} instead. + * Adds a separator with an unclickable label below it. The separator will be placed at the bottom of the menu. To add a + * separator at a specific point in the menu, use {@link Menu.addMenuItem} with {@link Menu.MenuItemProperties} instead. * @function Menu.addSeparator * @param {string} menuName - Name of the menu to add a separator to. * @param {string} separatorName - Name of the separator that will be displayed as the label below the separator line. * @example Add a separator. - * Menu.addSeparator("Developer","Test Separator"); + * Menu.addSeparator("Developer", "Test Separator"); */ void addSeparator(const QString& menuName, const QString& separatorName); /**jsdoc - * Remove a separator from a menu. + * Removes a separator from a menu. * @function Menu.removeSeparator * @param {string} menuName - Name of the menu to remove the separator from. * @param {string} separatorName - Name of the separator to remove. * @example Remove a separator. - * Menu.removeSeparator("Developer","Test Separator"); + * Menu.removeSeparator("Developer", "Test Separator"); */ void removeSeparator(const QString& menuName, const QString& separatorName); /**jsdoc - * Add a new menu item to a menu. + * Adds a new menu item to a menu. The menu item is specified using {@link Menu.MenuItemProperties}. * @function Menu.addMenuItem * @param {Menu.MenuItemProperties} properties - Properties of the menu item to create. - * @example Add a menu item using {@link Menu.MenuItemProperties}. + * @example Add a menu item at a particular position in the "Develope"r menu. * Menu.addMenuItem({ * menuName: "Developer", * menuItemName: "Test", * afterItem: "Log", - * shortcutKey: "Ctrl+Shift+T", - * grouping: "Advanced" + * shortcutKey: "Ctrl+Shift+T" * }); */ void addMenuItem(const MenuItemProperties& properties); /**jsdoc - * Add a new menu item to a menu. The new item is added at the end of the menu. + * Adds a new menu item to a menu. The new item is added at the end of the menu. * @function Menu.addMenuItem + * @variation 0 * @param {string} menuName - Name of the menu to add a menu item to. * @param {string} menuItem - Name of the menu item. This is what will be displayed in the menu. * @param {string} [shortcutKey] A shortcut key that can be used to trigger the menu item. @@ -146,7 +143,7 @@ public slots: void addMenuItem(const QString& menuName, const QString& menuitem); /**jsdoc - * Remove a menu item from a menu. + * Removes a menu item from a menu. * @function Menu.removeMenuItem * @param {string} menuName - Name of the menu to remove a menu item from. * @param {string} menuItem - Name of the menu item to remove. @@ -155,7 +152,7 @@ public slots: void removeMenuItem(const QString& menuName, const QString& menuitem); /**jsdoc - * Check if a menu item exists. + * Checks whether a menu item exists. * @function Menu.menuItemExists * @param {string} menuName - Name of the menu that the menu item is in. * @param {string} menuItem - Name of the menu item to check for existence of. @@ -168,66 +165,66 @@ public slots: bool menuItemExists(const QString& menuName, const QString& menuitem); /**jsdoc - * Check whether a checkable menu item is checked. + * Checks whether a checkable menu item is checked. * @function Menu.isOptionChecked * @param {string} menuOption - The name of the menu item. * @returns {boolean} true if the option is checked, otherwise false. - * @example Report whether the Settings > Advanced menu item is turned on. - * print(Menu.isOptionChecked("Advanced Menus")); // true or false + * @example Report whether the Settings > Developer menu item is turned on. + * print("Developer menu showing: " + Menu.isOptionChecked("Developer Menu")); */ bool isOptionChecked(const QString& menuOption); /**jsdoc - * Set a checkable menu item as checked or unchecked. + * Sets a checkable menu item as checked or unchecked. * @function Menu.setIsOptionChecked * @param {string} menuOption - The name of the menu item to modify. * @param {boolean} isChecked - If true, the menu item will be checked, otherwise it will not be checked. - * @example Turn on Settings > Advanced Menus. - * Menu.setIsOptionChecked("Advanced Menus", true); - * print(Menu.isOptionChecked("Advanced Menus")); // true + * @example Turn on Settings > Developer Menu. + * Menu.setIsOptionChecked("Developer Menu", true); + * print("Developer menu showing: " + Menu.isOptionChecked("Developer Menu")); */ void setIsOptionChecked(const QString& menuOption, bool isChecked); /**jsdoc - * Trigger the menu item as if the user clicked on it. + * Triggers a menu item as if the user clicked on it. * @function Menu.triggerOption * @param {string} menuOption - The name of the menu item to trigger. - * @example Open the help window. - * Menu.triggerOption('Help...'); + * @example Open the Asset Browser dialog. + * Menu.triggerOption('Asset Browser'); */ void triggerOption(const QString& menuOption); /**jsdoc - * Check whether a menu or menu item is enabled. If disabled, the item is grayed out and unusable. + * Checks whether a menu or menu item is enabled. If disabled, the item is grayed out and unusable. * Menus are enabled by default. * @function Menu.isMenuEnabled * @param {string} menuName The name of the menu or menu item to check. * @returns {boolean} true if the menu is enabled, otherwise false. - * @example Report with the Settings > Advanced Menus menu item is enabled. - * print(Menu.isMenuEnabled("Settings > Advanced Menus")); // true or false + * @example Report whether the Settings > Developer Menu item is enabled. + * print("Developer Menu item enabled: " + Menu.isMenuEnabled("Settings > Developer Menu")); */ bool isMenuEnabled(const QString& menuName); /**jsdoc - * Set a menu or menu item to be enabled or disabled. If disabled, the item is grayed out and unusable. + * Sets a menu or menu item to be enabled or disabled. If disabled, the item is grayed out and unusable. * @function Menu.setMenuEnabled * @param {string} menuName - The name of the menu or menu item to modify. * @param {boolean} isEnabled - If true, the menu will be enabled, otherwise it will be disabled. - * @example Disable the Settings > Advanced Menus menu item. - * Menu.setMenuEnabled("Settings > Advanced Menus", false); - * print(Menu.isMenuEnabled("Settings > Advanced Menus")); // false + * @example Disable the Settings > Developer Menu item. + * Menu.setMenuEnabled("Settings > Developer Menu", false); + * print("Developer Menu item enabled: " + Menu.isMenuEnabled("Settings > Developer Menu")); */ void setMenuEnabled(const QString& menuName, bool isEnabled); signals: /**jsdoc - * Triggered when a menu item is clicked (or triggered by {@link Menu.triggerOption}). + * Triggered when a menu item is clicked or triggered by {@link Menu.triggerOption}. * @function Menu.menuItemEvent - * @param {string} menuItem - Name of the menu item that was clicked. + * @param {string} menuItem - Name of the menu item that was clicked or triggered. * @returns {Signal} * @example Detect menu item events. * function onMenuItemEvent(menuItem) { - * print("You clicked on " + menuItem); + * print("Menu item clicked: " + menuItem); * } * * Menu.menuItemEvent.connect(onMenuItemEvent); diff --git a/libraries/script-engine/src/MenuItemProperties.cpp b/libraries/script-engine/src/MenuItemProperties.cpp index 2662ba406d..31aa0dd81c 100644 --- a/libraries/script-engine/src/MenuItemProperties.cpp +++ b/libraries/script-engine/src/MenuItemProperties.cpp @@ -57,18 +57,18 @@ QScriptValue menuItemPropertiesToScriptValue(QScriptEngine* engine, const MenuIt * the menu item will be placed at the end of the menu. * * @typedef {object} Menu.MenuItemProperties - * @property {string} menuName Name of the menu. Nested menus can be described using the ">" symbol. - * @property {string} menuItemName Name of the menu item. - * @property {boolean} [isCheckable=false] Whether or not the menu item is checkable. - * @property {boolean} [isChecked=false] Whether or not the menu item is checked. - * @property {boolean} [isSeparator=false] Whether or not the menu item is a separator. - * @property {string} [shortcutKey] A shortcut key that triggers the menu item. - * @property {KeyEvent} [shortcutKeyEvent] A {@link KeyEvent} that specifies a key that triggers the menu item. - * @property {number} [position] The position to place the new menu item. An integer number with 0 being the first + * @property {string} menuName - Name of the menu. Nested menus can be described using the ">" symbol. + * @property {string} menuItemName - Name of the menu item. + * @property {boolean} [isCheckable=false] - Whether or not the menu item is checkable. + * @property {boolean} [isChecked=false] - Whether or not the menu item is checked. + * @property {boolean} [isSeparator=false] - Whether or not the menu item is a separator. + * @property {string} [shortcutKey] - A shortcut key that triggers the menu item. + * @property {KeyEvent} [shortcutKeyEvent] - A {@link KeyEvent} that specifies a key that triggers the menu item. + * @property {number} [position] - The position to place the new menu item. An integer number with 0 being the first * menu item. - * @property {string} [beforeItem] The name of the menu item to place this menu item before. - * @property {string} [afterItem] The name of the menu item to place this menu item after. - * @property {string} [grouping] The name of grouping to add this menu item to. + * @property {string} [beforeItem] - The name of the menu item to place this menu item before. + * @property {string} [afterItem] - The name of the menu item to place this menu item after. + * @property {string} [grouping] - The name of grouping to add this menu item to. */ void menuItemPropertiesFromScriptValue(const QScriptValue& object, MenuItemProperties& properties) { properties.menuName = object.property("menuName").toVariant().toString(); From fbe49bbfd45e75d9aa2f3b1a49688002e63ef3de Mon Sep 17 00:00:00 2001 From: David Rowe Date: Sat, 27 Apr 2019 10:20:35 +1200 Subject: [PATCH 2/2] Doc review --- interface/src/scripting/MenuScriptingInterface.h | 11 ++++++----- libraries/script-engine/src/MenuItemProperties.cpp | 6 +++--- 2 files changed, 9 insertions(+), 8 deletions(-) diff --git a/interface/src/scripting/MenuScriptingInterface.h b/interface/src/scripting/MenuScriptingInterface.h index 1ab691ac59..6c2634b1de 100644 --- a/interface/src/scripting/MenuScriptingInterface.h +++ b/interface/src/scripting/MenuScriptingInterface.h @@ -26,7 +26,7 @@ class MenuItemProperties; *

A "grouping" provides a way to group a set of menus or menu items together so that they can all be set visible or invisible * as a group.

There is currently only one available group: "Developer". This grouping can be toggled in the * "Settings" menu.

- *

If a menu item doesn't belong to a group it is always displayed.

+ *

If a menu item doesn't belong to a group, it is always displayed.

* * @namespace Menu * @@ -85,7 +85,7 @@ public slots: /**jsdoc * Checks whether a top-level menu exists. * @function Menu.menuExists - * @param {string} menuName - Name of the menu to check for existence. + * @param {string} menuName - Name of the menu to check exists. * @returns {boolean} true if the menu exists, otherwise false. * @example Check if the "Developer" menu exists. * if (Menu.menuExists("Developer")) { @@ -98,7 +98,7 @@ public slots: * Adds a separator with an unclickable label below it. The separator will be placed at the bottom of the menu. To add a * separator at a specific point in the menu, use {@link Menu.addMenuItem} with {@link Menu.MenuItemProperties} instead. * @function Menu.addSeparator - * @param {string} menuName - Name of the menu to add a separator to. + * @param {string} menuName - Name of the menu to add the separator to. * @param {string} separatorName - Name of the separator that will be displayed as the label below the separator line. * @example Add a separator. * Menu.addSeparator("Developer", "Test Separator"); @@ -119,7 +119,7 @@ public slots: * Adds a new menu item to a menu. The menu item is specified using {@link Menu.MenuItemProperties}. * @function Menu.addMenuItem * @param {Menu.MenuItemProperties} properties - Properties of the menu item to create. - * @example Add a menu item at a particular position in the "Develope"r menu. + * @example Add a menu item at a particular position in the "Developer" menu. * Menu.addMenuItem({ * menuName: "Developer", * menuItemName: "Test", @@ -133,7 +133,7 @@ public slots: * Adds a new menu item to a menu. The new item is added at the end of the menu. * @function Menu.addMenuItem * @variation 0 - * @param {string} menuName - Name of the menu to add a menu item to. + * @param {string} menuName - Name of the menu to add the menu item to. * @param {string} menuItem - Name of the menu item. This is what will be displayed in the menu. * @param {string} [shortcutKey] A shortcut key that can be used to trigger the menu item. * @example Add a menu item to the end of the "Developer" menu. @@ -147,6 +147,7 @@ public slots: * @function Menu.removeMenuItem * @param {string} menuName - Name of the menu to remove a menu item from. * @param {string} menuItem - Name of the menu item to remove. + * @example Remove a menu item from the "Developer" menu. * Menu.removeMenuItem("Developer", "Test"); */ void removeMenuItem(const QString& menuName, const QString& menuitem); diff --git a/libraries/script-engine/src/MenuItemProperties.cpp b/libraries/script-engine/src/MenuItemProperties.cpp index 31aa0dd81c..af9c4a3d0a 100644 --- a/libraries/script-engine/src/MenuItemProperties.cpp +++ b/libraries/script-engine/src/MenuItemProperties.cpp @@ -53,11 +53,11 @@ QScriptValue menuItemPropertiesToScriptValue(QScriptEngine* engine, const MenuIt /**jsdoc * A set of properties that can be passed to {@link Menu.addMenuItem} to create a new menu item. * - * If none of position, beforeItem, afterItem, or grouping are specified, - * the menu item will be placed at the end of the menu. + * If none of the properties, position, beforeItem, afterItem, or grouping + * are specified, the menu item will be placed at the end of the menu. * * @typedef {object} Menu.MenuItemProperties - * @property {string} menuName - Name of the menu. Nested menus can be described using the ">" symbol. + * @property {string} menuName - Name of the menu. Nested menus can be described using the ">" character. * @property {string} menuItemName - Name of the menu item. * @property {boolean} [isCheckable=false] - Whether or not the menu item is checkable. * @property {boolean} [isChecked=false] - Whether or not the menu item is checked.