From 277ef56f4941e9d7d9742be7a23406b3b05fd516 Mon Sep 17 00:00:00 2001
From: David Rowe <david@ctrlaltstudio.com>
Date: Thu, 14 Mar 2019 10:24:19 +1300
Subject: [PATCH] Fill in JSDoc for new flow functions

---
 interface/src/avatar/MyAvatar.cpp | 33 +++++++++++++++++++++++++++++++
 interface/src/avatar/MyAvatar.h   | 15 +++++++-------
 2 files changed, 41 insertions(+), 7 deletions(-)

diff --git a/interface/src/avatar/MyAvatar.cpp b/interface/src/avatar/MyAvatar.cpp
index e0353da1b4..e0e9b5b648 100644
--- a/interface/src/avatar/MyAvatar.cpp
+++ b/interface/src/avatar/MyAvatar.cpp
@@ -5443,6 +5443,39 @@ void MyAvatar::useFlow(bool isActive, bool isCollidable, const QVariantMap& phys
     }
 }
 
+/**jsdoc
+ * Flow options currently used in flow simulation.
+ * @typedef {object} MyAvatar.FlowData
+ * @property {boolean} initialized - <code>true</code> if flow has been initialized for the current avatar, <code>false</code> 
+ *     if it hasn't.
+ * @property {boolean} active - <code>true</code> if flow is enabled, <code>false</code> if it isn't.
+ * @property {boolean} colliding - <code>true</code> if collisions are enabled, <code>false</code> if they aren't.
+ * @property {Object<GroupName, MyAvatar.FlowPhysicsData>} physicsData - The physics configuration for each group of joints 
+ *     that has been configured.
+ * @property {Object<JointName, MyAvatar.FlowCollisionsData>} collisions - The collisions configuration for each joint that 
+ *     has collisions configured.
+ * @property {Object<ThreadName, number[]>} threads - The threads hat have been configured, with the name of the first joint as 
+ *     the <code>ThreadName</code> and an array of the indexes of all the joints in the thread as the value.
+ */
+/**jsdoc
+ * A set of physics options currently used in flow simulation.
+ * @typedef {object} MyAvatar.FlowPhysicsData
+ * @property {boolean} active - <code>true</code> to enable flow on the joint, <code>false</code> if it isn't.,
+ * @property {number} radius - The thickness of segments and knots. (Needed for collisions.)
+ * @property {number} gravity - Y-value of the gravity vector.
+ * @property {number} inertia - Rotational inertia multiplier.
+ * @property {number} damping - The amount of damping on joint oscillation.
+ * @property {number} stiffness - How stiff each thread is.
+ * @property {number} delta - Delta time for every integration step.
+ * @property {number[]} jointIndices - The indexes of the joints the options are applied to.
+ */
+/**jsdoc
+ * A set of collision options currently used in flow simulation.
+ * @typedef {object} MyAvatar.FlowCollisionsData
+ * @property {number} radius - Collision sphere radius.
+ * @property {number} offset - Offset of the collision sphere from the joint.
+ * @property {number} jointIndex - The index of the joint the options are applied to.
+ */
 QVariantMap MyAvatar::getFlowData() {
     QVariantMap result;
     if (QThread::currentThread() != thread()) {
diff --git a/interface/src/avatar/MyAvatar.h b/interface/src/avatar/MyAvatar.h
index c7585311b8..bd112bfacc 100755
--- a/interface/src/avatar/MyAvatar.h
+++ b/interface/src/avatar/MyAvatar.h
@@ -1563,16 +1563,17 @@ public:
     Q_INVOKABLE void useFlow(bool isActive, bool isCollidable, const QVariantMap& physicsConfig = QVariantMap(), const QVariantMap& collisionsConfig = QVariantMap());
 
     /**jsdoc
-    * @function MyAvatar.getFlowData
-    * @returns {object}
-    */
+     * Gets the current flow configuration.
+     * @function MyAvatar.getFlowData
+     * @returns {MyAvatar.FlowData}
+     */
     Q_INVOKABLE QVariantMap getFlowData();
 
     /**jsdoc
-    * returns the indices of every colliding flow joint
-    * @function MyAvatar.getCollidingFlowJoints
-    * @returns {int[]}
-    */
+     * Gets the indexes of currently colliding flow joints.
+     * @function MyAvatar.getCollidingFlowJoints
+     * @returns {number[]} The indexes of currently colliding flow joints.
+     */
     Q_INVOKABLE QVariantList getCollidingFlowJoints();
 
 public slots: