Merge branch 'DOC-55-B' into api-docs

libraries/entities/src/EntityScriptingInterface.h

@@ -1867,7 +1867,8 @@ public slots:
      * @function Entities.getMeshes
      * @param {Uuid} entityID - The ID of the <code>Model</code> or <code>PolyVox</code> entity to get the meshes of.
      * @param {Entities~getMeshesCallback} callback - The function to call upon completion.
-     * @deprecated This function is deprecated and will be removed. Use the {@link Graphics} API instead.
+     * @deprecated This function is deprecated and will be removed. It no longer works for Model entities. Use the 
+     *     {@link Graphics} API instead.
      */
      /**jsdoc
       * Called when a {@link Entities.getMeshes} call is complete.
@@ -1876,7 +1877,8 @@ public slots:
       *     <code>Model</code> or <code>PolyVox</code> entity; otherwise <code>undefined</code>. 
       * @param {boolean} success - <code>true</code> if the {@link Entities.getMeshes} call was successful, <code>false</code> 
       *     otherwise. The call may be unsuccessful if the requested entity could not be found.
-      * @deprecated This function is deprecated and will be removed. Use the {@link Graphics} API instead.
+      * @deprecated This function is deprecated and will be removed. It no longer works for Model entities. Use the 
+      *     {@link Graphics} API instead. 
       */
     // FIXME move to a renderable entity interface
     Q_INVOKABLE void getMeshes(const QUuid& entityID, QScriptValue callback);

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:

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));

libraries/shared/src/RegisteredMetaTypes.h

@@ -687,7 +687,8 @@ namespace graphics {
 using MeshPointer = std::shared_ptr<graphics::Mesh>;
 
 /**jsdoc
- * A handle for a mesh in an entity, such as returned by {@link Entities.getMeshes}.
+ * A mesh, such as returned by {@link Entities.getMeshes} or {@link Model} API functions.
+ *
  * @class MeshProxy
  *
  * @hifi-interface
@@ -705,16 +706,16 @@ public:
     virtual MeshPointer getMeshPointer() const = 0;
     
     /**jsdoc
-     * Get the number of vertices in the mesh.
+     * Gets the number of vertices in the mesh.
      * @function MeshProxy#getNumVertices
      * @returns {number} Integer number of vertices in the mesh.
      */
     Q_INVOKABLE virtual int getNumVertices() const = 0;
 
     /**jsdoc
-     * Get the position of a vertex in the mesh.
+     * Gets the position of a vertex in the mesh.
      * @function MeshProxy#getPos
-     * @param {number} index - Integer index of the mesh vertex.
+     * @param {number} index - Integer index of the vertex.
      * @returns {Vec3} Local position of the vertex relative to the mesh.
      */
     Q_INVOKABLE virtual glm::vec3 getPos(int index) const = 0;