From ec86b82079eed8da622560c98e011bbaa69ff879 Mon Sep 17 00:00:00 2001 From: Ryan Huffman Date: Mon, 14 Nov 2016 12:14:24 -0800 Subject: [PATCH 1/4] Add jsdoc to Camera --- interface/src/Camera.h | 57 ++++++++++++++++++++++++++++++++++-------- 1 file changed, 47 insertions(+), 10 deletions(-) diff --git a/interface/src/Camera.h b/interface/src/Camera.h index 792dcb4a40..27904242ab 100644 --- a/interface/src/Camera.h +++ b/interface/src/Camera.h @@ -35,9 +35,22 @@ __attribute__((unused)) #endif static int cameraModeId = qRegisterMetaType(); +/**jsdoc + * @global + */ class Camera : public QObject { Q_OBJECT - + + /**jsdoc + * @namespace Camera + * @property position {Vec3} The position of the camera. + * @property orientation {Quat} The orientation of the camera. + * @property mode {string} The current camera mode. + * @property cameraEntity {EntityID} The position and rotation properties of + * the entity specified by this ID are then used as the camera's position and + * orientation. Only works when mode is "entity". + * @property frustum {Object} The frustum of the camera. + */ Q_PROPERTY(glm::vec3 position READ getPosition WRITE setPosition) Q_PROPERTY(glm::quat orientation READ getOrientation WRITE setOrientation) Q_PROPERTY(QString mode READ getModeString WRITE setModeString) @@ -47,13 +60,13 @@ class Camera : public QObject { public: Camera(); - void initialize(); // instantly put the camera at the ideal position and orientation. + void initialize(); // instantly put the camera at the ideal position and orientation. void update( float deltaTime ); CameraMode getMode() const { return _mode; } void setMode(CameraMode m); - + void loadViewFrustum(ViewFrustum& frustum) const; ViewFrustum toViewFrustum() const; @@ -80,20 +93,44 @@ public slots: QUuid getCameraEntity() const; void setCameraEntity(QUuid entityID); + /**jsdoc + * Compute a {PickRay} based on the current camera configuration and the position x,y on the screen. + * @function Camera.computePickRay + * @param {float} x + * @param {float} y + * @return {PickRay} + */ PickRay computePickRay(float x, float y); - // These only work on independent cameras - /// one time change to what the camera is looking at - void lookAt(const glm::vec3& value); + /**jsdoc + * Set the camera to look at position position. Only works while in independent. + * camera mode. + * @function Camera.lookAt + * @param {Vec3} position position to look at + */ + void lookAt(const glm::vec3& position); - /// fix what the camera is looking at, and keep the camera looking at this even if position changes - void keepLookingAt(const glm::vec3& value); + /**jsdoc + * Set the camera to continue looking at position position. + * Only works while in `independent` camera mode. + * @function Camera.keepLookingAt + * @param {Vec3} position position to look at + */ + void keepLookingAt(const glm::vec3& position); - /// stops the keep looking at feature, doesn't change what's being looked at, but will stop camera from - /// continuing to update it's orientation to keep looking at the item + /**jsdoc + * Stops the camera from continually looking at a position that was set with + * `keepLookingAt` + * @function Camera.stopLookingAt + */ void stopLooking() { _isKeepLookingAt = false; } signals: + /**jsdoc + * Triggered when camera mode has changed. + * @function Camera.modeUpdated + * @return {Signal} + */ void modeUpdated(const QString& newMode); private: From 7e2bb0e5ed028e664d5cb709032016a99fba7933 Mon Sep 17 00:00:00 2001 From: Ryan Huffman Date: Mon, 14 Nov 2016 13:51:51 -0800 Subject: [PATCH 2/4] Cleanup camera docs --- interface/src/Camera.h | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/interface/src/Camera.h b/interface/src/Camera.h index 27904242ab..cedfb3f185 100644 --- a/interface/src/Camera.h +++ b/interface/src/Camera.h @@ -35,9 +35,6 @@ __attribute__((unused)) #endif static int cameraModeId = qRegisterMetaType(); -/**jsdoc - * @global - */ class Camera : public QObject { Q_OBJECT @@ -96,9 +93,9 @@ public slots: /**jsdoc * Compute a {PickRay} based on the current camera configuration and the position x,y on the screen. * @function Camera.computePickRay - * @param {float} x - * @param {float} y - * @return {PickRay} + * @param {float} x X-coordinate on screen. + * @param {float} y Y-coordinate on screen. + * @return {PickRay} The computed {PickRay}. */ PickRay computePickRay(float x, float y); @@ -106,7 +103,7 @@ public slots: * Set the camera to look at position position. Only works while in independent. * camera mode. * @function Camera.lookAt - * @param {Vec3} position position to look at + * @param {Vec3} Position Position to look at. */ void lookAt(const glm::vec3& position); @@ -114,7 +111,7 @@ public slots: * Set the camera to continue looking at position position. * Only works while in `independent` camera mode. * @function Camera.keepLookingAt - * @param {Vec3} position position to look at + * @param {Vec3} position Position to keep looking at. */ void keepLookingAt(const glm::vec3& position); From 3fcc2d3fa5d344a3f66cd40f979e021e56a89b92 Mon Sep 17 00:00:00 2001 From: Ryan Huffman Date: Mon, 14 Nov 2016 13:52:16 -0800 Subject: [PATCH 3/4] Add jsdoc to Clipboard --- .../scripting/ClipboardScriptingInterface.h | 51 ++++++++++++++++--- 1 file changed, 44 insertions(+), 7 deletions(-) diff --git a/interface/src/scripting/ClipboardScriptingInterface.h b/interface/src/scripting/ClipboardScriptingInterface.h index 4737a194df..3c10475242 100644 --- a/interface/src/scripting/ClipboardScriptingInterface.h +++ b/interface/src/scripting/ClipboardScriptingInterface.h @@ -13,6 +13,9 @@ #include +/**jsdoc + * @namespace Clipboard + */ class ClipboardScriptingInterface : public QObject { Q_OBJECT public: @@ -21,13 +24,47 @@ public: signals: void readyToImport(); -public slots: - glm::vec3 getContentsDimensions(); /// returns the overall dimensions of everything on the blipboard - float getClipboardContentsLargestDimension(); /// returns the largest dimension of everything on the clipboard - bool importEntities(const QString& filename); - bool exportEntities(const QString& filename, const QVector& entityIDs); - bool exportEntities(const QString& filename, float x, float y, float z, float s); - QVector pasteEntities(glm::vec3 position); +public: + /**jsdoc + * @function Clipboard.getContentsDimensions + * @return {Vec3} The extents of the contents held in the clipboard. + */ + Q_INVOKABLE glm::vec3 getContentsDimensions(); + + /**jsdoc + * Compute largest dimension of the extents of the contents held in the clipboard + * @function Clipboard.getClipboardContentsLargestDimension + * @return {float} The largest dimension computed. + */ + Q_INVOKABLE float getClipboardContentsLargestDimension(); + + /**jsdoc + * Import entities from a .json file containing entity data into the clipboard. + * You can generate * a .json file using {Clipboard.exportEntities}. + * @function Clipboard.importEntities + * @param {string} filename Filename of file to import. + * @return {bool} True if the import was succesful, otherwise false. + */ + Q_INVOKABLE bool importEntities(const QString& filename); + + /**jsdoc + * Export the entities listed in `entityIDs` to the file `filename` + * @function Clipboard.exportEntities + * @param {string} filename Path to the file to export entities to. + * @param {EntityID[]} entityIDs IDs of entities to export. + * @return {bool} True if the export was succesful, otherwise false. + */ + Q_INVOKABLE bool exportEntities(const QString& filename, const QVector& entityIDs); + Q_INVOKABLE bool exportEntities(const QString& filename, float x, float y, float z, float s); + + /**jsdoc + * Paste the contents of the clipboard into the world. + * @function Clipboard.pasteEntities + * @param {Vec3} position Position to paste clipboard at. + * @return {EntityID[]} Array of entity IDs for the new entities that were + * created as a result of the paste operation. + */ + Q_INVOKABLE QVector pasteEntities(glm::vec3 position); }; #endif // hifi_ClipboardScriptingInterface_h From 5fd1ae64b0b2f124141e627a5d1eb61e7bf6aebe Mon Sep 17 00:00:00 2001 From: Ryan Huffman Date: Mon, 14 Nov 2016 16:54:55 -0800 Subject: [PATCH 4/4] Begin adding entities jsdoc --- .../entities/src/EntityScriptingInterface.h | 69 ++++++++++++++++--- tools/jsdoc/plugins/hifi.js | 1 + 2 files changed, 62 insertions(+), 8 deletions(-) diff --git a/libraries/entities/src/EntityScriptingInterface.h b/libraries/entities/src/EntityScriptingInterface.h index 3d46113611..7cef753de9 100644 --- a/libraries/entities/src/EntityScriptingInterface.h +++ b/libraries/entities/src/EntityScriptingInterface.h @@ -56,6 +56,9 @@ QScriptValue RayToEntityIntersectionResultToScriptValue(QScriptEngine* engine, c void RayToEntityIntersectionResultFromScriptValue(const QScriptValue& object, RayToEntityIntersectionResult& results); +/**jsdoc + * @namespace Entities + */ /// handles scripting of Entity commands from JS passed to assigned clients class EntityScriptingInterface : public OctreeScriptingInterface, public Dependency { Q_OBJECT @@ -87,40 +90,90 @@ public: ActivityTracking getActivityTracking() const { return _activityTracking; } public slots: - // returns true if the DomainServer will allow this Node/Avatar to make changes + /**jsdoc + * Returns `true` if the DomainServer will allow this Node/Avatar to make changes + * + * @function Entities.canAdjustLocks + * @return {bool} `true` if the client can adjust locks, `false` if not. + */ Q_INVOKABLE bool canAdjustLocks(); - // returns true if the DomainServer will allow this Node/Avatar to rez new entities + /**jsdoc + * @function Entities.canRez + * @return {bool} `true` if the DomainServer will allow this Node/Avatar to rez new entities + */ Q_INVOKABLE bool canRez(); + + /**jsdoc + * @function Entities.canRezTmp + * @return {bool} `true` if the DomainServer will allow this Node/Avatar to rez new temporary entities + */ Q_INVOKABLE bool canRezTmp(); - /// adds a model with the specific properties + /**jsdoc + * Add a new entity with the specified properties. If `clientOnly` is true, the entity will + * not be sent to the server and will only be visible/accessible on the local client. + * + * @function Entities.addEntity + * @param {EntityItemProperties} properties Properties of the entity to create. + * @param {bool} [clientOnly=false] Whether the entity should only exist locally or not. + * @return {EntityID} The entity ID of the newly created entity. The ID will be a null + * UUID (`{00000000-0000-0000-0000-000000000000}`) if the entity could not be created. + */ Q_INVOKABLE QUuid addEntity(const EntityItemProperties& properties, bool clientOnly = false); /// temporary method until addEntity can be used from QJSEngine + /// Deliberately not adding jsdoc, only used internally. Q_INVOKABLE QUuid addModelEntity(const QString& name, const QString& modelUrl, const QString& shapeType, bool dynamic, const glm::vec3& position, const glm::vec3& gravity); - /// gets the current model properties for a specific model - /// this function will not find return results in script engine contexts which don't have access to models + /**jsdoc + * Return the properties for the specified {EntityID}. + * not be sent to the server and will only be visible/accessible on the local client. + * @param {EntityItemProperties} properties Properties of the entity to create. + * @param {EntityPropertyFlags} [desiredProperties=[]] Array containing the names of the properties you + * would like to get. If the array is empty, all properties will be returned. + * @return {EntityItemProperties} The entity properties for the specified entity. + */ Q_INVOKABLE EntityItemProperties getEntityProperties(QUuid entityID); Q_INVOKABLE EntityItemProperties getEntityProperties(QUuid identity, EntityPropertyFlags desiredProperties); - /// edits a model updating only the included properties, will return the identified EntityItemID in case of - /// successful edit, if the input entityID is for an unknown model this function will have no effect + /**jsdoc + * Updates an entity with the specified properties. + * + * @function Entities.editEntity + * @return {EntityID} The EntityID of the entity if the edit was successful, otherwise the null {EntityID}. + */ Q_INVOKABLE QUuid editEntity(QUuid entityID, const EntityItemProperties& properties); - /// deletes a model + /**jsdoc + * Deletes an entity. + * + * @function Entities.deleteEntity + * @param {EntityID} entityID The ID of the entity to delete. + */ Q_INVOKABLE void deleteEntity(QUuid entityID); /// Allows a script to call a method on an entity's script. The method will execute in the entity script /// engine. If the entity does not have an entity script or the method does not exist, this call will have /// no effect. + /**jsdoc + * Call a method on an entity. If it is running an entity script (specified by the `script` property) + * and it exposes a property with the specified name `method`, it will be called + * using `params` as the list of arguments. + * + * @function Entities.callEntityMethod + * @param {EntityID} entityID The ID of the entity to call the method on. + * @param {string} method The name of the method to call. + * @param {string[]} params The list of parameters to call the specified method with. + */ Q_INVOKABLE void callEntityMethod(QUuid entityID, const QString& method, const QStringList& params = QStringList()); /// finds the closest model to the center point, within the radius /// will return a EntityItemID.isKnownID = false if no models are in the radius /// this function will not find any models in script engine contexts which don't have access to models + /**jsdoc + */ Q_INVOKABLE QUuid findClosestEntity(const glm::vec3& center, float radius) const; /// finds models within the search sphere specified by the center point and radius diff --git a/tools/jsdoc/plugins/hifi.js b/tools/jsdoc/plugins/hifi.js index 8016aa2ae5..084ff57fb5 100644 --- a/tools/jsdoc/plugins/hifi.js +++ b/tools/jsdoc/plugins/hifi.js @@ -19,6 +19,7 @@ exports.handlers = { '../../libraries/script-engine/src', '../../libraries/networking/src', '../../libraries/animation/src', + '../../libraries/entities/src', ]; var exts = ['.h', '.cpp'];