From a45d8924fa5e40b7273e376d6ea2164671eb7733 Mon Sep 17 00:00:00 2001
From: David Rowe <david@ctrlaltstudio.com>
Date: Thu, 11 Jul 2019 16:31:09 +1200
Subject: [PATCH] Miscellaneous minor JSDoc fixes noticed in passing
---
.../src/raypick/PickScriptingInterface.h | 4 ++--
.../src/raypick/RayPickScriptingInterface.h | 4 ++--
interface/src/scripting/Audio.h | 2 +-
.../src/scripting/HMDScriptingInterface.h | 2 +-
.../src/scripting/WindowScriptingInterface.h | 2 +-
.../entities/src/EntityItemProperties.cpp | 4 ++--
.../entities/src/EntityScriptingInterface.h | 23 ++++++++++++++-----
libraries/entities/src/ShapeEntityItem.cpp | 2 +-
libraries/pointers/src/Pick.h | 2 +-
libraries/shared/src/PickFilter.h | 2 +-
libraries/shared/src/RenderLayer.h | 4 ++--
11 files changed, 31 insertions(+), 20 deletions(-)
diff --git a/interface/src/raypick/PickScriptingInterface.h b/interface/src/raypick/PickScriptingInterface.h
index 1cbdaa92f7..d8654e2a13 100644
--- a/interface/src/raypick/PickScriptingInterface.h
+++ b/interface/src/raypick/PickScriptingInterface.h
@@ -29,7 +29,7 @@
* @property {FilterFlags} PICK_AVATAR_ENTITIES - Include avatar entities when intersecting. <em>Read-only.</em>
* @property {FilterFlags} PICK_LOCAL_ENTITIES - Include local entities when intersecting. <em>Read-only.</em>
* @property {FilterFlags} PICK_AVATARS - Include avatars when intersecting. <em>Read-only.</em>
- * @property {FilterFlags} PICK_HUD - Include the HUD sphere when intersecting in HMD mode. <em>Read-only.</em>
+ * @property {FilterFlags} PICK_HUD - Include the HUD surface when intersecting in HMD mode. <em>Read-only.</em>
*
* @property {FilterFlags} PICK_ENTITIES - Include domain and avatar entities when intersecting. <em>Read-only.</em>
* <p class="important">Deprecated: This property is deprecated and will be removed. Use <code>PICK_DOMAIN_ENTITIES |
@@ -61,7 +61,7 @@
* <p class="important">Deprecated: This property is deprecated and will be removed. Use
* <code>INTERSECTED_LOCAL_ENTITY</code> instead.</p>
* @property {IntersectionType} INTERSECTED_AVATAR - Intersected an avatar. <em>Read-only.</em>
- * @property {IntersectionType} INTERSECTED_HUD - Intersected the HUD sphere. <em>Read-only.</em>
+ * @property {IntersectionType} INTERSECTED_HUD - Intersected the HUD surface. <em>Read-only.</em>
*
* @property {number} perFrameTimeBudget - The maximum time, in microseconds, to spend per frame updating pick results.
*/
diff --git a/interface/src/raypick/RayPickScriptingInterface.h b/interface/src/raypick/RayPickScriptingInterface.h
index 32a2ec4a5d..41972ca52d 100644
--- a/interface/src/raypick/RayPickScriptingInterface.h
+++ b/interface/src/raypick/RayPickScriptingInterface.h
@@ -33,7 +33,7 @@
* <em>Read-only.</em>
* @property {FilterFlags} PICK_OVERLAYS - Include local entities when intersecting. <em>Read-only.</em>
* @property {FilterFlags} PICK_AVATARS - Include avatars when intersecting. <em>Read-only.</em>
- * @property {FilterFlags} PICK_HUD - Include the HUD sphere when intersecting in HMD mode. <em>Read-only.</em>
+ * @property {FilterFlags} PICK_HUD - Include the HUD surface when intersecting in HMD mode. <em>Read-only.</em>
* @property {FilterFlags} PICK_PRECISE - Pick against exact meshes. <em>Read-only.</em>
* @property {FilterFlags} PICK_INCLUDE_INVISIBLE - Include invisible objects when intersecting. <em>Read-only.</em>
* @property {FilterFlags} PICK_INCLUDE_NONCOLLIDABLE - Include non-collidable objects when intersecting. <em>Read-only.</em>
@@ -43,7 +43,7 @@
* @property {IntersectionType} INTERSECTED_LOCAL_ENTITY - Intersected a local entity. <em>Read-only.</em>
* @property {IntersectionType} INTERSECTED_OVERLAY - Intersected an entity (3D Overlays no longer exist). <em>Read-only.</em>
* @property {IntersectionType} INTERSECTED_AVATAR - Intersected an avatar. <em>Read-only.</em>
- * @property {IntersectionType} INTERSECTED_HUD - Intersected the HUD sphere. <em>Read-only.</em>
+ * @property {IntersectionType} INTERSECTED_HUD - Intersected the HUD surface. <em>Read-only.</em>
*/
class RayPickScriptingInterface : public QObject, public Dependency {
Q_OBJECT
diff --git a/interface/src/scripting/Audio.h b/interface/src/scripting/Audio.h
index d62fd70cc4..aab1ade95b 100644
--- a/interface/src/scripting/Audio.h
+++ b/interface/src/scripting/Audio.h
@@ -459,7 +459,7 @@ signals:
/**jsdoc
* Triggered when the server injector gain changes.
* @function Audio.serverInjectorGainChanged
- * @param {float} gain - The new server injector gain value.
+ * @param {number} gain - The new server injector gain value.
* @returns {Signal}
*/
void serverInjectorGainChanged(float gain);
diff --git a/interface/src/scripting/HMDScriptingInterface.h b/interface/src/scripting/HMDScriptingInterface.h
index 335816bf7c..0f636a388b 100644
--- a/interface/src/scripting/HMDScriptingInterface.h
+++ b/interface/src/scripting/HMDScriptingInterface.h
@@ -62,7 +62,7 @@ class QScriptEngine;
* @property {Uuid} miniTabletScreenID - The UUID of the mini tablet's screen entity. <code>null</code> if not in HMD mode.
* @property {number} miniTabletHand - The hand that the mini tablet is displayed on: <code>0</code> for left hand,
* <code>1</code> for right hand, <code>-1</code> if not in HMD mode.
- * @property {bool} miniTabletEnabled=true - <code>true</code> if the mini tablet is enabled to be displayed, otherwise
+ * @property {boolean} miniTabletEnabled=true - <code>true</code> if the mini tablet is enabled to be displayed, otherwise
* <code>false</code>.
* @property {Rect} playArea=0,0,0,0 - The size and position of the HMD play area in sensor coordinates. <em>Read-only.</em>
* @property {Vec3[]} sensorPositions=[]] - The positions of the VR system sensors in sensor coordinates. <em>Read-only.</em>
diff --git a/interface/src/scripting/WindowScriptingInterface.h b/interface/src/scripting/WindowScriptingInterface.h
index eab1c65ebb..b5b7f3c8b9 100644
--- a/interface/src/scripting/WindowScriptingInterface.h
+++ b/interface/src/scripting/WindowScriptingInterface.h
@@ -666,7 +666,7 @@ signals:
/**jsdoc
* Triggered when the interstitial mode changes.
* @function Window.interstitialModeChanged
- * @param {bool} interstitialMode - The new interstitial mode value. If <code>true</code>, the interstitial graphics are
+ * @param {boolean} interstitialMode - The new interstitial mode value. If <code>true</code>, the interstitial graphics are
* displayed when the domain is loading.
* @returns {Signal}
*/
diff --git a/libraries/entities/src/EntityItemProperties.cpp b/libraries/entities/src/EntityItemProperties.cpp
index 064fe2e3b1..003985bfa3 100644
--- a/libraries/entities/src/EntityItemProperties.cpp
+++ b/libraries/entities/src/EntityItemProperties.cpp
@@ -987,8 +987,8 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* <code>false</code> otherwise; <code>[]</code> if none are applied or the model hasn't loaded. The array indexes are per
* {@link Entities.getJointIndex|getJointIndex}.
* @property {Vec3[]} jointTranslations=[]] - Joint translations applied to the model; <code>[]</code> if none are applied or
- * the model hasn't loaded. The array indexes are per {@link Entities.getJointIndex|getJointIndex}. Rotations are relative
- * to each joint's parent.
+ * the model hasn't loaded. The array indexes are per {@link Entities.getJointIndex|getJointIndex}. Translations are
+ * relative to each joint's parent.
* <p>Joint translations can be set by {@link Entities.setLocalJointTranslation|setLocalJointTranslation} and similar
* functions, or by setting the value of this property. If you set a joint translation using this property you also need to
* set the corresponding <code>jointTranslationsSet</code> value to <code>true</code>.</p>
diff --git a/libraries/entities/src/EntityScriptingInterface.h b/libraries/entities/src/EntityScriptingInterface.h
index ad2aaf2160..0442756300 100644
--- a/libraries/entities/src/EntityScriptingInterface.h
+++ b/libraries/entities/src/EntityScriptingInterface.h
@@ -446,7 +446,15 @@ public slots:
/**jsdoc
* Gets an entity's script object. In particular, this is useful for accessing a {@link Entities.EntityProperties-Web|Web}
* entity's HTML <code>EventBridge</code> script object to exchange messages with the web page script.
- * <p>Alternatively, you can use {@link Entities.emitScriptEvent} and {@link Entities.webEventReceived} to exchange
+ * <p>To send a message from an Interface script to a Web entity over its event bridge:</p>
+ * <pre class="prettyprint"><code>var entityObject = Entities.getEntityObject(entityID);
+ * entityObject.emitScriptEvent(message);</code></pre>
+ * <p>To receive a message from a Web entity over its event bridge in an Interface script:</p>
+ * <pre class="prettyprint"><code>var entityObject = Entities.getentityObject(entityID);
+ * entityObject.webEventReceived.connect(function(message) {
+ * ...
+ * };</code></pre>
+ * <p>Alternatively, you can use {@link Entities.emitScriptEvent} and {@link Entities.webEventReceived} to exchange
* messages with a Web entity over its event bridge.</p>
* @function Entities.getEntityObject
* @param {Uuid} id - The ID of the entity to get the script object for.
@@ -459,7 +467,7 @@ public slots:
* <title>HELLO</title>
* </head>
* <body>
- * <h1>HELLO</h1></h1>
+ * <h1>HELLO</h1>
* <script>
* function onScriptEventReceived(message) {
* // Message received from the script.
@@ -476,7 +484,7 @@ public slots:
* </body>
* </html>
*
- * // Script file.
+ * // Interface script file.
* var webEntity = Entities.addEntity({
* type: "Web",
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -3 })),
@@ -525,9 +533,12 @@ public slots:
Q_INVOKABLE bool isAddedEntity(const QUuid& id);
/**jsdoc
- * Calculates the size of some text in a text entity.
+ * Calculates the size of some text in a {@link Entities.EntityProperties-Text|Text} entity. The entity need not be set
+ * visible.
+ * <p><strong>Note:</strong> The size of text in a Text entity cannot be calculated immediately after the
+ * entity is created; a short delay is required while the entity finishes being created.</p>
* @function Entities.textSize
- * @param {Uuid} id - The ID of the entity to use for calculation.
+ * @param {Uuid} id - The ID of the Text entity to use for calculation.
* @param {string} text - The string to calculate the size of.
* @returns {Size} The size of the <code>text</code> in meters if the object is a text entity, otherwise
* <code>{ height: 0, width : 0 }</code>.
@@ -1794,7 +1805,7 @@ public slots:
* <title>HELLO</title>
* </head>
* <body>
- * <h1>HELLO</h1></h1>
+ * <h1>HELLO</h1>
* <script>
* function onScriptEventReceived(message) {
* // Message received from the script.
diff --git a/libraries/entities/src/ShapeEntityItem.cpp b/libraries/entities/src/ShapeEntityItem.cpp
index 513daa0b09..ae4d17fa66 100644
--- a/libraries/entities/src/ShapeEntityItem.cpp
+++ b/libraries/entities/src/ShapeEntityItem.cpp
@@ -30,8 +30,8 @@ namespace entity {
* </thead>
* <tbody>
* <tr><td><code>"Circle"</code></td><td>2D</td><td>A circle oriented in 3D.</td></tr>
- * <tr><td><code>"Cube"</code></td><td>3D</td><td></td></tr>
* <tr><td><code>"Cone"</code></td><td>3D</td><td></td></tr>
+ * <tr><td><code>"Cube"</code></td><td>3D</td><td></td></tr>
* <tr><td><code>"Cylinder"</code></td><td>3D</td><td></td></tr>
* <tr><td><code>"Dodecahedron"</code></td><td>3D</td><td></td></tr>
* <tr><td><code>"Hexagon"</code></td><td>3D</td><td>A hexagonal prism.</td></tr>
diff --git a/libraries/pointers/src/Pick.h b/libraries/pointers/src/Pick.h
index 1766736664..4adb571a5a 100644
--- a/libraries/pointers/src/Pick.h
+++ b/libraries/pointers/src/Pick.h
@@ -31,7 +31,7 @@
* <tr><td>INTERSECTED_ENTITY</td><td><code>1</code></td><td>Intersected an entity.</td></tr>
* <tr><td>INTERSECTED_LOCAL_ENTITY</td><td><code>2</code></td><td>Intersected a local entity.</td></tr>
* <tr><td>INTERSECTED_AVATAR</td><td><code>3</code></td><td>Intersected an avatar.</td></tr>
- * <tr><td>INTERSECTED_HUD</td><td><code>4</code></td><td>Intersected the HUD sphere.</td></tr>
+ * <tr><td>INTERSECTED_HUD</td><td><code>4</code></td><td>Intersected the HUD surface.</td></tr>
* </tbody>
* </table>
* @typedef {number} IntersectionType
diff --git a/libraries/shared/src/PickFilter.h b/libraries/shared/src/PickFilter.h
index 9b7f763e6a..5e5f5db3bc 100644
--- a/libraries/shared/src/PickFilter.h
+++ b/libraries/shared/src/PickFilter.h
@@ -26,7 +26,7 @@ public:
* <tr><td>PICK_AVATAR_ENTITIES</td><td><code>2</code></td><td>Include avatar entities when intersecting.</td></tr>
* <tr><td>PICK_LOCAL_ENTITIES</td><td><code>4</code></td><td>Include local entities when intersecting.</td></tr>
* <tr><td>PICK_AVATATRS</td><td><code>8</code></td><td>Include avatars when intersecting.</td></tr>
- * <tr><td>PICK_HUD</td><td><code>16</code></td><td>Include the HUD sphere when intersecting in HMD mode.</td></tr>
+ * <tr><td>PICK_HUD</td><td><code>16</code></td><td>Include the HUD surface when intersecting in HMD mode.</td></tr>
* <tr><td>PICK_INCLUDE_VISIBLE</td><td><code>32</code></td><td>Include visible objects when intersecting.</td></tr>
* <tr><td>PICK_INCLUDE_INVISIBLE</td><td><code>64</code></td><td>Include invisible objects when intersecting.</td></tr>
* <tr><td>PICK_INCLUDE_COLLIDABLE</td><td><code>128</code></td><td>Include collidable objects when
diff --git a/libraries/shared/src/RenderLayer.h b/libraries/shared/src/RenderLayer.h
index c95ceb192c..caa1e54f58 100644
--- a/libraries/shared/src/RenderLayer.h
+++ b/libraries/shared/src/RenderLayer.h
@@ -19,8 +19,8 @@
* </thead>
* <tbody>
* <tr><td><code>"world"</code></td><td>The entity is drawn in the world with everything else.</td></tr>
- * <tr><td><code>"front"</code></td><td>The entity is drawn on top of the world layer but behind the HUD sphere.</td></tr>
- * <tr><td><code>"hud"</code></td><td>The entity is drawn on top of other layers and the HUD sphere.</td></tr>
+ * <tr><td><code>"front"</code></td><td>The entity is drawn on top of the world layer but behind the HUD surface.</td></tr>
+ * <tr><td><code>"hud"</code></td><td>The entity is drawn on top of other layers and the HUD surface.</td></tr>
* </tbody>
* </table>
* @typedef {string} Entities.RenderLayer