From 1ebc6a575e1fe7f8b38d22de0957a57cfba0c298 Mon Sep 17 00:00:00 2001
From: David Rowe <david@ctrlaltstudio.com>
Date: Fri, 20 Dec 2019 13:33:48 +1300
Subject: [PATCH] Model API JSDoc

---
 .../src/ModelScriptingInterface.h             | 60 +++++++++++++++++++
 libraries/shared/src/RegisteredMetaTypes.cpp  |  5 ++
 2 files changed, 65 insertions(+)

diff --git a/libraries/script-engine/src/ModelScriptingInterface.h b/libraries/script-engine/src/ModelScriptingInterface.h
index 3c239f006f..39170bb370 100644
--- a/libraries/script-engine/src/ModelScriptingInterface.h
+++ b/libraries/script-engine/src/ModelScriptingInterface.h
@@ -17,19 +17,79 @@
 #include <RegisteredMetaTypes.h>
 class QScriptEngine;
 
+/**jsdoc
+ * The <code>Model</code> API provides the ability to manipulate meshes. You can get the meshes for an entity using 
+ * {@link Entities.getMeshes}, or create a new mesh using {@link Model.newMesh}.
+ * <p>See also, the {@link Graphics} API.</p>
+ *
+ * @namespace Model
+ *
+ * @hifi-interface
+ * @hifi-client-entity
+ * @hifi-avatar
+ * @hifi-server-entity
+ * @hifi-assignment-client
+ *
+ * @deprecated This API is deprecated. Use the {@link Graphics} API instead.
+ */
 class ModelScriptingInterface : public QObject {
     Q_OBJECT
 
 public:
     ModelScriptingInterface(QObject* parent);
 
+    /**jsdoc
+     * Exports meshes to an OBJ format model.
+     * @function Model.meshToOBJ
+     * @param {MeshProxy[]} meshes - The meshes to export.
+     * @returns {string} The OBJ format representation of the meshes.
+     */
     Q_INVOKABLE QString meshToOBJ(MeshProxyList in);
+
+    /**jsdoc
+     * Combines multiple meshes into one.
+     * @function Model.appendMeshes
+     * @param {MeshProxy[]} meshes - The meshes to combine.
+     * @returns {MeshProxy} The combined mesh.
+     */
     Q_INVOKABLE QScriptValue appendMeshes(MeshProxyList in);
+
+    /**jsdoc
+     * Transforms the vertices in a mesh.
+     * @function Model.transformMesh
+     * @param {Mat4} transform - The transform to apply.
+     * @param {MeshProxy} mesh - The mesh to apply the transform to.
+     * @returns {MeshProxy|boolean} The transformed mesh, if valid. <code>false</code> if an error.
+     */
     Q_INVOKABLE QScriptValue transformMesh(glm::mat4 transform, MeshProxy* meshProxy);
+
+    /**jsdoc
+     * Creates a new mesh.
+     * @function Model.newMesh
+     * @param {Vec3[]} vertices - The vertices in the mesh.
+     * @param {Vec3[]} normals - The normals in the mesh.
+     * @param {MeshFace[]} faces - The faces in the mesh.
+     * @returns {MeshProxy} A new mesh.
+     */
     Q_INVOKABLE QScriptValue newMesh(const QVector<glm::vec3>& vertices,
                                      const QVector<glm::vec3>& normals,
                                      const QVector<MeshFace>& faces);
+
+    /**jsdoc
+     * Gets the number of vertices in a mesh.
+     * @function Model.getVertexCount
+     * @param {MeshProxy} mesh - The mesh to count the vertices in.
+     * @returns {number|boolean} The number of vertices in the mesh, if valid. <code>false</code> if an error.
+     */
     Q_INVOKABLE QScriptValue getVertexCount(MeshProxy* meshProxy);
+
+    /**jsdoc
+     * Gets the position of a vertex in a mesh.
+     * @function Model.getVertex
+     * @param {MeshProxy} mesh - The mesh.
+     * @param {number} index - The index of the vertex to get.
+     * @returns {Vec3|boolean} The local position of the vertex relative to the mesh, if valid. <code>false</code> if an error.
+     */
     Q_INVOKABLE QScriptValue getVertex(MeshProxy* meshProxy, int vertexIndex);
 
 private:
diff --git a/libraries/shared/src/RegisteredMetaTypes.cpp b/libraries/shared/src/RegisteredMetaTypes.cpp
index 87cd269c97..7c30d4f205 100644
--- a/libraries/shared/src/RegisteredMetaTypes.cpp
+++ b/libraries/shared/src/RegisteredMetaTypes.cpp
@@ -1306,6 +1306,11 @@ void meshesFromScriptValue(const QScriptValue& value, MeshProxyList &out) {
 }
 
 
+/**jsdoc
+ * A triangle in a mesh.
+ * @typedef {object} MeshFace
+ * @property {number[]} vertices - The indexes of the three vertices that make up the fase.
+ */
 QScriptValue meshFaceToScriptValue(QScriptEngine* engine, const MeshFace &meshFace) {
     QScriptValue obj = engine->newObject();
     obj.setProperty("vertices", qVectorIntToScriptValue(engine, meshFace.vertexIndices));