Add jsdoc comments to Menu

interface/src/scripting/MenuScriptingInterface.h

@@ -17,6 +17,30 @@
 
 class MenuItemProperties;
 
+/**jsdoc
+ * The `Menu` provides access to the menu that is shown at the top of the window
+ * shown on a user's desktop and the right click menu that is accessible
+ * in both Desktop and HMD mode.
+ *
+ * <h3>Groupings</h3>
+ * A `grouping` is a way to group a set of menus and/or menu items together
+ * so that they can all be set visible or invisible as a group. There are
+ * 2 available groups: "Advanced" and "Developer"
+ * These groupings can be toggled in the "Settings" menu.
+ *
+ * @namespace Menu
+ */
+
+/**
+ * CURRENTLY NOT WORKING:
+ *
+ * <h3>Action groups</h3>
+ * When 1+ menu items are checkable and in the same action group, only 1 can be
+ * selected at any one time. If another item in the action group is selected, the
+ * previous will be deselected. This feature provides the ability to create
+ * "radio-button"-like menus.
+ */
+
 class MenuScriptingInterface : public QObject {
     Q_OBJECT
     MenuScriptingInterface() { };
@@ -28,33 +52,142 @@ private slots:
     void menuItemTriggered();
 
 public slots:
+    /**jsdoc
+     * Add a new top-level menu.
+     * @function Menu.addMenu
+     * @param {string} menuName Name that will be shown in the menu.
+     * @param {string} grouping Name of the grouping to add this menu to.
+     */
     void addMenu(const QString& menuName, const QString& grouping = QString());
+
+    /**jsdoc
+     * Remove a top-level menu.
+     * @function Menu.removeMenu
+     * @param {string} menuName Name of the menu to remove.
+     */
     void removeMenu(const QString& menuName);
+
+    /**jsdoc
+     * Check whether a top-level menu exists.
+     * @function Menu.menuExists
+     * @param {string} menuName Name of the menu to check for existence.
+     * @return {bool} `true` if the menu exists, otherwise `false`.
+     */
     bool menuExists(const QString& menuName);
 
+    /**jsdoc
+     * Add a separator with an unclickable label below it.
+     * The line will be placed at the bottom of the menu.
+     * @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 shown (but unclickable) below the separator line.
+     */
     void addSeparator(const QString& menuName, const QString& separatorName);
+
+    /**jsdoc
+     * Remove a separator and its label from a menu.
+     * @function Menu.removeSeparator
+     * @param {string} menuName Name of the menu to remove a separator from.
+     * @param {string} separatorName Name of the separator to remove.
+     */
     void removeSeparator(const QString& menuName, const QString& separatorName);
 
+    /**jsdoc
+     * Add a new menu item to a menu.
+     * @function Menu.addMenuItem
+     * @param {Menu.MenuItemProperties} properties
+     */
     void addMenuItem(const MenuItemProperties& properties);
+
+    /**jsdoc
+     * Add a new menu item to a menu.
+     * @function Menu.addMenuItem
+     * @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.
+     */
     void addMenuItem(const QString& menuName, const QString& menuitem, const QString& shortcutKey);
+
+    /**jsdoc
+     * Add a new menu item to a menu.
+     * @function Menu.addMenuItem
+     * @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.
+     */
     void addMenuItem(const QString& menuName, const QString& menuitem);
 
+    /**jsdoc
+     * Remove 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.
+     */
     void removeMenuItem(const QString& menuName, const QString& menuitem);
+
+    /**jsdoc
+     * Check if 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.
+     * @return {bool} `true` if the menu item exists, otherwise `false`.
+     */
     bool menuItemExists(const QString& menuName, const QString& menuitem);
 
+    /**
+     * Not working, will not document until fixed
+     */
     void addActionGroup(const QString& groupName, const QStringList& actionList,
                         const QString& selected = QString());
     void removeActionGroup(const QString& groupName);
 
+    /**jsdoc
+     * Check whether a checkable menu item is checked.
+     * @function Menu.isOptionChecked
+     * @param {string} menuOption The name of the menu item.
+     * @return `true` if the option is checked, otherwise false.
+     */
     bool isOptionChecked(const QString& menuOption);
+
+    /**jsdoc
+     * Set a checkable menu item as checked or unchecked.
+     * @function Menu.setIsOptionChecked
+     * @param {string} menuOption The name of the menu item to modify.
+     * @param {bool} isChecked If `true`, the menu item will be checked, otherwise it will not be checked.
+     */
     void setIsOptionChecked(const QString& menuOption, bool isChecked);
 
+    /**jsdoc
+     * Toggle the status of a checkable menu item. If it is checked, it will be unchecked.
+     * If it is unchecked, it will be checked.
+     * @function Menu.setIsOptionChecked
+     * @param {string} menuOption The name of the menu item to toggle.
+     */
     void triggerOption(const QString& menuOption);
 
+    /**jsdoc
+     * Check whether a menu is enabled. If a menu is disabled it will be greyed out
+     * and unselectable.
+     * Menus are enabled by default.
+     * @function Menu.isMenuEnabled
+     * @param {string} menuName The name of the menu to check.
+     * @return {bool} `true` if the menu is enabled, otherwise false.
+     */
     bool isMenuEnabled(const QString& menuName);
+
+    /**jsdoc
+     * Set a menu to be enabled or disabled.
+     * @function Menu.setMenuEnabled
+     * @param {string} menuName The name of the menu to modify.
+     * @param {bool} isEnabled Whether the menu will be enabled or not.
+     */
     void setMenuEnabled(const QString& menuName, bool isEnabled);
 
 signals:
+    /**jsdoc
+     * This is a signal that is emitted when a menu item is clicked.
+     * @function Menu.menuItemEvent
+     * @param {string} menuItem Name of the menu item that was triggered.
+     */
     void menuItemEvent(const QString& menuItem);
 };
 

libraries/script-engine/src/MenuItemProperties.cpp

@@ -50,6 +50,24 @@ QScriptValue menuItemPropertiesToScriptValue(QScriptEngine* engine, const MenuIt
     return obj;
 }
 
+/**jsdoc
+ * `MenuItemProperties` is a list of properties that can be passed to Menu.addMenuItem
+ * to create a new menu item.
+ *
+ * If none of position, beforeItem, afterItem, or grouping are specified, the
+ * menu item will be placed in the last position.
+ *
+ * @typedef {Object} Menu.MenuItemProperties
+ * @property {string} menuName Name of the top-level menu
+ * @property {string} menuItemName Name of the menu item
+ * @property {bool} isCheckable Whether the menu item is checkable or not
+ * @property {bool} isChecked Where the menu item is checked or not
+ * @property {string} shortcutKey An optional shortcut key to trigger the menu item.
+ * @property {int} position The position to place the new menu item. `0` is 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.
+ */
 void menuItemPropertiesFromScriptValue(const QScriptValue& object, MenuItemProperties& properties) {
     properties.menuName = object.property("menuName").toVariant().toString();
     properties.menuItemName = object.property("menuItemName").toVariant().toString();