From aa53ab7492b15f183754fc11f7886539364ae29a Mon Sep 17 00:00:00 2001
From: David Rowe <david@ctrlaltstudio.com>
Date: Wed, 27 Feb 2019 09:54:11 +1300
Subject: [PATCH] Distinguish between Mat4 type and Mat4 API in JSDoc

---
 libraries/script-engine/src/Mat4.h         | 33 +++++++++++-----------
 libraries/shared/src/RegisteredMetaTypes.h | 21 ++++++++++++++
 2 files changed, 38 insertions(+), 16 deletions(-)

diff --git a/libraries/script-engine/src/Mat4.h b/libraries/script-engine/src/Mat4.h
index 7ad77b9b24..0cdc70e79c 100644
--- a/libraries/script-engine/src/Mat4.h
+++ b/libraries/script-engine/src/Mat4.h
@@ -23,6 +23,7 @@
 
 /**jsdoc
  * @namespace Mat4
+ * @variation 0
  *
  * @hifi-interface
  * @hifi-client-entity
@@ -38,7 +39,7 @@ class Mat4 : public QObject, protected QScriptable {
 public slots:
 
     /**jsdoc
-     * @function Mat4.multiply
+     * @function Mat4(0).multiply
      * @param {Mat4} m1
      * @param {Mat4} m2
      * @returns {Mat4}
@@ -47,7 +48,7 @@ public slots:
 
 
     /**jsdoc
-     * @function Mat4.createFromRotAndTrans
+     * @function Mat4(0).createFromRotAndTrans
      * @param {Quat} rot
      * @param {Vec3} trans
      * @returns {Mat4}
@@ -55,7 +56,7 @@ public slots:
     glm::mat4 createFromRotAndTrans(const glm::quat& rot, const glm::vec3& trans) const;
 
     /**jsdoc
-     * @function Mat4.createFromScaleRotAndTrans
+     * @function Mat4(0).createFromScaleRotAndTrans
      * @param {Vec3} scale
      * @param {Quat} rot
      * @param {Vec3} trans
@@ -64,7 +65,7 @@ public slots:
     glm::mat4 createFromScaleRotAndTrans(const glm::vec3& scale, const glm::quat& rot, const glm::vec3& trans) const;
 
     /**jsdoc
-     * @function Mat4.createFromColumns
+     * @function Mat4(0).createFromColumns
      * @param {Vec4} col0
      * @param {Vec4} col1
      * @param {Vec4} col2
@@ -74,7 +75,7 @@ public slots:
     glm::mat4 createFromColumns(const glm::vec4& col0, const glm::vec4& col1, const glm::vec4& col2, const glm::vec4& col3) const;
 
     /**jsdoc
-     * @function Mat4.createFromArray
+     * @function Mat4(0).createFromArray
      * @param {number[]} numbers
      * @returns {Mat4}
      */
@@ -82,21 +83,21 @@ public slots:
 
 
     /**jsdoc
-     * @function Mat4.extractTranslation
+     * @function Mat4(0).extractTranslation
      * @param {Mat4} m
      * @returns {Vec3}
      */
     glm::vec3 extractTranslation(const glm::mat4& m) const;
 
     /**jsdoc
-     * @function Mat4.extractRotation
+     * @function Mat4(0).extractRotation
      * @param {Mat4} m
      * @returns {Vec3}
      */
     glm::quat extractRotation(const glm::mat4& m) const;
 
     /**jsdoc
-     * @function Mat4.extractScale
+     * @function Mat4(0).extractScale
      * @param {Mat4} m
      * @returns {Vec3}
      */
@@ -104,7 +105,7 @@ public slots:
 
 
     /**jsdoc
-     * @function Mat4.transformPoint
+     * @function Mat4(0).transformPoint
      * @param {Mat4} m
      * @param {Vec3} point
      * @returns {Vec3}
@@ -112,7 +113,7 @@ public slots:
     glm::vec3 transformPoint(const glm::mat4& m, const glm::vec3& point) const;
 
     /**jsdoc
-     * @function Mat4.transformVector
+     * @function Mat4(0).transformVector
      * @param {Mat4} m
      * @param {Vec3} vector
      * @returns {Vec3}
@@ -121,7 +122,7 @@ public slots:
 
 
     /**jsdoc
-     * @function Mat4.inverse
+     * @function Mat4(0).inverse
      * @param {Mat4} m
      * @returns {Mat4}
      */
@@ -129,7 +130,7 @@ public slots:
 
 
     /**jsdoc
-     * @function Mat4.getFront
+     * @function Mat4(0).getFront
      * @param {Mat4} m
      * @returns {Vec3}
      */
@@ -137,28 +138,28 @@ public slots:
     glm::vec3 getFront(const glm::mat4& m) const { return getForward(m); }
 
     /**jsdoc
-     * @function Mat4.getForward
+     * @function Mat4(0).getForward
      * @param {Mat4} m
      * @returns {Vec3}
      */
     glm::vec3 getForward(const glm::mat4& m) const;
 
     /**jsdoc
-     * @function Mat4.getRight
+     * @function Mat4(0).getRight
      * @param {Mat4} m
      * @returns {Vec3}
      */
     glm::vec3 getRight(const glm::mat4& m) const;
 
     /**jsdoc
-     * @function Mat4.getUp
+     * @function Mat4(0).getUp
      * @param {Mat4} m
      * @returns {Vec3}
      */
     glm::vec3 getUp(const glm::mat4& m) const;
 
     /**jsdoc
-     * @function Mat4.print
+     * @function Mat4(0).print
      * @param {string} label
      * @param {Mat4} m
      * @param {boolean} [transpose=false]
diff --git a/libraries/shared/src/RegisteredMetaTypes.h b/libraries/shared/src/RegisteredMetaTypes.h
index 1edb303455..ea2c5b8354 100644
--- a/libraries/shared/src/RegisteredMetaTypes.h
+++ b/libraries/shared/src/RegisteredMetaTypes.h
@@ -43,6 +43,27 @@ Q_DECLARE_METATYPE(std::function<QVariant()>);
 void registerMetaTypes(QScriptEngine* engine);
 
 // Mat4
+/**jsdoc
+ * A 4 x 4 matrix, typically containing a scale, rotation, and translation transform. See also the {@link Mat4(0)|Mat4} object.
+ *
+ * @typedef {object} Mat4
+ * @property {number} r0c0 - Row 0, column 0 value.
+ * @property {number} r1c0 - Row 1, column 0 value.
+ * @property {number} r2c0 - Row 2, column 0 value.
+ * @property {number} r3c0 - Row 3, column 0 value.
+ * @property {number} r0c1 - Row 0, column 1 value.
+ * @property {number} r1c1 - Row 1, column 1 value.
+ * @property {number} r2c1 - Row 2, column 1 value.
+ * @property {number} r3c1 - Row 3, column 1 value.
+ * @property {number} r0c2 - Row 0, column 2 value.
+ * @property {number} r1c2 - Row 1, column 2 value.
+ * @property {number} r2c2 - Row 2, column 2 value.
+ * @property {number} r3c2 - Row 3, column 2 value.
+ * @property {number} r0c3 - Row 0, column 3 value.
+ * @property {number} r1c3 - Row 1, column 3 value.
+ * @property {number} r2c3 - Row 2, column 3 value.
+ * @property {number} r3c3 - Row 3, column 3 value.
+ */
 QScriptValue mat4toScriptValue(QScriptEngine* engine, const glm::mat4& mat4);
 void mat4FromScriptValue(const QScriptValue& object, glm::mat4& mat4);