From b793e23cb096b922de2f793619e3c2de926ce94f Mon Sep 17 00:00:00 2001
From: David Rowe <david@ctrlaltstudio.com>
Date: Tue, 15 Oct 2019 15:24:41 +1300
Subject: [PATCH] Keyboard JSDoc

---
 .../scripting/KeyboardScriptingInterface.h    | 61 ++++++++++++++++++-
 1 file changed, 58 insertions(+), 3 deletions(-)

diff --git a/interface/src/scripting/KeyboardScriptingInterface.h b/interface/src/scripting/KeyboardScriptingInterface.h
index 41c5ab7644..dc680b05cf 100644
--- a/interface/src/scripting/KeyboardScriptingInterface.h
+++ b/interface/src/scripting/KeyboardScriptingInterface.h
@@ -18,15 +18,23 @@
 #include "DependencyManager.h"
 
 /**jsdoc
- * The Keyboard API provides facilities to use 3D Physical keyboard.
+ * The <code>Keyboard</code> API provides facilities to use an in-world, virtual keyboard. When enabled, this keyboard is 
+ * displayed instead of the 2D keyboard that raises at the bottom of the tablet or Web entities when a text input field has 
+ * focus and you're in HMD mode.
+ *
  * @namespace Keyboard
  *
  * @hifi-interface
  * @hifi-client-entity
  * @hifi-avatar
  *
- * @property {bool} raised - <code>true</code> If the keyboard is visible <code>false</code> otherwise
- * @property {bool} password - <code>true</code> Will show * instead of characters in the text display <code>false</code> otherwise
+ * @property {boolean} raised - <code>true</code> if the virtual keyboard is visible, <code>false</code> if it isn't.
+ * @property {boolean} password - <code>true</code> if <code>"*"</code>s are displayed on the virtual keyboard's display 
+ *     instead of the characters typed, <code>false</code> if the actual characters are displayed.
+ * @property {boolean} use3DKeyboard - <code>true</code> if user settings have "Use Virtual Keyboard" enabled, 
+ *     <code>false</code> if it's disabled. <em>Read-only.</em>
+ * @property {boolean} preferMalletsOverLasers - <code>true</code> if user settings for the virtual keyboard have "Mallets" 
+ *     selected, <code>false</code> if "Lasers" is selected. <em>Read-only.</em>
  */
 
 class KeyboardScriptingInterface : public QObject, public Dependency {
@@ -39,14 +47,61 @@ class KeyboardScriptingInterface : public QObject, public Dependency {
 public:
     KeyboardScriptingInterface() = default;
     ~KeyboardScriptingInterface() = default;
+
+    /**jsdoc
+     * Loads a JSON file that defines the virtual keyboard's layout. The default JSON file used is 
+     * {@link https://github.com/highfidelity/hifi/blob/master/interface/resources/config/keyboard.json|https://github.com/highfidelity/hifi/.../keyboard.json}.
+     * @function Keyboard.loadKeyboardFile
+     * @param {string} path - The keyboard JSON file.
+     */
     Q_INVOKABLE void loadKeyboardFile(const QString& string);
+
+    /**jsdoc
+     * Enables the left mallet so that it is displayed when in HMD mode.
+     * @function Keyboard.enableLeftMallet
+     */
     Q_INVOKABLE void enableLeftMallet();
+
+    /**jsdoc
+     * Enables the right mallet so that it is displayed when in HMD mode.
+     * @function Keyboard.enableRightMallet
+     */
     Q_INVOKABLE void enableRightMallet();
+
+    /**jsdoc
+     * Disables the left mallet so that it is not displayed when in HMD mode.
+     * @function Keyboard.disableLeftMallet
+     */
     Q_INVOKABLE void disableLeftMallet();
+
+    /**jsdoc
+     * Disables the right mallet so that it is not displayed when in HMD mode.
+     * @function Keyboard.disableRightMallet
+     */
     Q_INVOKABLE void disableRightMallet();
+
+    /**jsdoc
+     * Configures the virtual keyboard to recognize a ray pointer as the left hand's laser.
+     * @function Keyboard.setLeftHandLaser
+     * @param {number} leftHandLaser - The ID of a ray pointer created by {@link Pointers.createPointer}.
+     */
     Q_INVOKABLE void setLeftHandLaser(unsigned int leftHandLaser);
+
+    /**jsdoc
+     * Configures the virtual keyboard to recognize a ray pointer as the right hand's laser.
+     * @function Keyboard.setRightHandLaser
+     * @param {number} rightHandLaser - The ID of a ray pointer created by {@link Pointers.createPointer}.
+     */
     Q_INVOKABLE void setRightHandLaser(unsigned int rightHandLaser);
+
+    /**jsdoc
+     * Checks whether an entity is part of the virtual keyboard.
+     * @function Keyboard.containsID
+     * @param {Uuid} entityID - The entity ID.
+     * @returns {boolean} <code>true</code> if the entity is part of the virtual keyboard, <code>false</code> if it isn't.
+     */
     Q_INVOKABLE bool containsID(const QUuid& overlayID) const;
+
 private:
     bool getPreferMalletsOverLasers() const;
     bool isRaised() const;