From 1bc38cab28b62e004d60d1f721154ec5c52f54df Mon Sep 17 00:00:00 2001 From: David Rowe Date: Thu, 4 Apr 2019 18:03:14 +1300 Subject: [PATCH 1/2] Camera JSDoc polish --- interface/src/FancyCamera.h | 56 +++++++++++-------- libraries/shared/src/shared/Camera.h | 84 +++++++++++----------------- 2 files changed, 65 insertions(+), 75 deletions(-) diff --git a/interface/src/FancyCamera.h b/interface/src/FancyCamera.h index 4ca073fb4f..cd587279e1 100644 --- a/interface/src/FancyCamera.h +++ b/interface/src/FancyCamera.h @@ -19,14 +19,22 @@ class FancyCamera : public Camera { Q_OBJECT /**jsdoc - * @namespace - * @augments Camera - */ - - // FIXME: JSDoc 3.5.5 doesn't augment @property definitions. The following definition is repeated in Camera.h. - /**jsdoc - * @property {Uuid} cameraEntity The ID of the entity that the camera position and orientation follow when the camera is in - * entity mode. + * The Camera API provides access to the "camera" that defines your view in desktop and HMD display modes. + * + * @namespace Camera + * + * @hifi-interface + * @hifi-client-entity + * @hifi-avatar + * + * @property {Vec3} position - The position of the camera. You can set this value only when the camera is in independent + * mode. + * @property {Quat} orientation - The orientation of the camera. You can set this value only when the camera is in + * independent mode. + * @property {Camera.Mode} mode - The camera mode. + * @property {ViewFrustum} frustum - The camera frustum. + * @property {Uuid} cameraEntity - The ID of the entity that is used for the camera position and orientation when the + * camera is in entity mode. */ Q_PROPERTY(QUuid cameraEntity READ getCameraEntity WRITE setCameraEntity) @@ -38,25 +46,25 @@ public: public slots: - /**jsdoc - * Get the ID of the entity that the camera is set to use the position and orientation from when it's in entity mode. You can - * also get the entity ID using the Camera.cameraEntity property. - * @function Camera.getCameraEntity - * @returns {Uuid} The ID of the entity that the camera is set to follow when in entity mode; null if no camera - * entity has been set. - */ + /**jsdoc + * Gets the ID of the entity that the camera is set to use the position and orientation from when it's in entity mode. You + * can also get the entity ID using the {@link Camera|Camera.cameraEntity} property. + * @function Camera.getCameraEntity + * @returns {Uuid} The ID of the entity that the camera is set to follow when in entity mode; null if no + * camera entity has been set. + */ QUuid getCameraEntity() const; /**jsdoc - * Set the entity that the camera should use the position and orientation from when it's in entity mode. You can also set the - * entity using the Camera.cameraEntity property. - * @function Camera.setCameraEntity - * @param {Uuid} entityID The entity that the camera should follow when it's in entity mode. - * @example Move your camera to the position and orientation of the closest entity. - * Camera.setModeString("entity"); - * var entity = Entities.findClosestEntity(MyAvatar.position, 100.0); - * Camera.setCameraEntity(entity); - */ + * Sets the entity that the camera should use the position and orientation from when it's in entity mode. You can also set + * the entity using the {@link Camera|Camera.cameraEntity} property. + * @function Camera.setCameraEntity + * @param {Uuid} entityID - The entity that the camera should follow when it's in entity mode. + * @example Move your camera to the position and orientation of the closest entity. + * Camera.setModeString("entity"); + * var entity = Entities.findClosestEntity(MyAvatar.position, 100.0); + * Camera.setCameraEntity(entity); + */ void setCameraEntity(QUuid entityID); private: diff --git a/libraries/shared/src/shared/Camera.h b/libraries/shared/src/shared/Camera.h index 0132e58d18..f41183479c 100644 --- a/libraries/shared/src/shared/Camera.h +++ b/libraries/shared/src/shared/Camera.h @@ -36,25 +36,6 @@ static int cameraModeId = qRegisterMetaType(); class Camera : public QObject { Q_OBJECT - /**jsdoc - * The Camera API provides access to the "camera" that defines your view in desktop and HMD display modes. - * - * @namespace Camera - * - * @hifi-interface - * @hifi-client-entity - * @hifi-avatar - * - * @property {Vec3} position - The position of the camera. You can set this value only when the camera is in independent - * mode. - * @property {Quat} orientation - The orientation of the camera. You can set this value only when the camera is in - * independent mode. - * @property {Camera.Mode} mode - The camera mode. - * @property {ViewFrustum} frustum - The camera frustum. - * @property {Uuid} cameraEntity - The ID of the entity that is used for the camera position and orientation when the - * camera is in entity mode. - */ - // FIXME: The cameraEntity property definition is copied from FancyCamera.h. 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) @@ -82,53 +63,54 @@ public: public slots: /**jsdoc - * Get the current camera mode. You can also get the mode using the Camera.mode property. + * Gets the current camera mode. You can also get the mode using the {@link Camera|Camera.mode} property. * @function Camera.getModeString * @returns {Camera.Mode} The current camera mode. */ QString getModeString() const; /**jsdoc - * Set the camera mode. You can also set the mode using the Camera.mode property. - * @function Camera.setModeString - * @param {Camera.Mode} mode - The mode to set the camera to. - */ + * Sets the camera mode. You can also set the mode using the {@link Camera|Camera.mode} property. + * @function Camera.setModeString + * @param {Camera.Mode} mode - The mode to set the camera to. + */ void setModeString(const QString& mode); /**jsdoc - * Get the current camera position. You can also get the position using the Camera.position property. - * @function Camera.getPosition - * @returns {Vec3} The current camera position. - */ + * Gets the current camera position. You can also get the position using the {@link Camera|Camera.position} property. + * @function Camera.getPosition + * @returns {Vec3} The current camera position. + */ glm::vec3 getPosition() const { return _position; } /**jsdoc - * Set the camera position. You can also set the position using the Camera.position property. Only works if the - * camera is in independent mode. - * @function Camera.setPosition - * @param {Vec3} position - The position to set the camera at. - */ + * Sets the camera position. You can also set the position using the {@link Camera|Camera.position} property. Only works if + * the camera is in independent mode. + * @function Camera.setPosition + * @param {Vec3} position - The position to set the camera at. + */ void setPosition(const glm::vec3& position); /**jsdoc - * Get the current camera orientation. You can also get the orientation using the Camera.orientation property. - * @function Camera.getOrientation - * @returns {Quat} The current camera orientation. - */ + * Gets the current camera orientation. You can also get the orientation using the {@link Camera|Camera.orientation} + * property. + * @function Camera.getOrientation + * @returns {Quat} The current camera orientation. + */ glm::quat getOrientation() const { return _orientation; } /**jsdoc - * Set the camera orientation. You can also set the orientation using the Camera.orientation property. Only - * works if the camera is in independent mode. - * @function Camera.setOrientation - * @param {Quat} orientation - The orientation to set the camera to. - */ + * Sets the camera orientation. You can also set the orientation using the {@link Camera|Camera.orientation} property. Only + * works if the camera is in independent mode. + * @function Camera.setOrientation + * @param {Quat} orientation - The orientation to set the camera to. + */ void setOrientation(const glm::quat& orientation); /**jsdoc - * Compute a {@link PickRay} based on the current camera configuration and the specified x, y position on the - * screen. The {@link PickRay} can be used in functions such as {@link Entities.findRayIntersection} and - * {@link Overlays.findRayIntersection}. + * Computes a {@link PickRay} based on the current camera configuration and the specified x, y position on the + * screen. The {@link PickRay} can be used in functions such as {@link Entities.findRayIntersection} and + * {@link Overlays.findRayIntersection}. * @function Camera.computePickRay * @param {number} x - X-coordinate on screen. * @param {number} y - Y-coordinate on screen. @@ -147,9 +129,9 @@ public slots: virtual PickRay computePickRay(float x, float y) const = 0; /**jsdoc - * Rotate the camera to look at the specified position. Only works if the camera is in independent mode. + * Rotates the camera to look at the specified position. Only works if the camera is in independent mode. * @function Camera.lookAt - * @param {Vec3} position - Position to look at. + * @param {Vec3} position - The position to look at. * @example Rotate your camera to look at entities as you click on them with your mouse. * function onMousePressEvent(event) { * var pickRay = Camera.computePickRay(event.x, event.y); @@ -168,15 +150,15 @@ public slots: void lookAt(const glm::vec3& position); /**jsdoc - * Set the camera to continue looking at the specified position even while the camera moves. Only works if the - * camera is in independent mode. + * Sets the camera to continue looking at the specified position even while the camera moves. Only works if + * the camera is in independent mode. * @function Camera.keepLookingAt - * @param {Vec3} position - Position to keep looking at. + * @param {Vec3} position - The position to keep looking at. */ void keepLookingAt(const glm::vec3& position); /**jsdoc - * Stops the camera from continually looking at the position that was set with Camera.keepLookingAt. + * Stops the camera from continually looking at the position that was set with {@link Camera.keepLookingAt}. * @function Camera.stopLookingAt */ void stopLooking() { _isKeepLookingAt = false; } From a7b1d613d33295a1f57035dd37d32a8dd0c64eae Mon Sep 17 00:00:00 2001 From: David Rowe Date: Thu, 11 Apr 2019 10:27:17 +1200 Subject: [PATCH 2/2] Doc review updates --- interface/src/FancyCamera.h | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/interface/src/FancyCamera.h b/interface/src/FancyCamera.h index cd587279e1..aead54d0fd 100644 --- a/interface/src/FancyCamera.h +++ b/interface/src/FancyCamera.h @@ -47,8 +47,8 @@ public: public slots: /**jsdoc - * Gets the ID of the entity that the camera is set to use the position and orientation from when it's in entity mode. You - * can also get the entity ID using the {@link Camera|Camera.cameraEntity} property. + * Gets the ID of the entity that the camera is set to follow (i.e., use the position and orientation from) when it's in + * entity mode. You can also get the entity ID using the {@link Camera|Camera.cameraEntity} property. * @function Camera.getCameraEntity * @returns {Uuid} The ID of the entity that the camera is set to follow when in entity mode; null if no * camera entity has been set. @@ -56,8 +56,8 @@ public slots: QUuid getCameraEntity() const; /**jsdoc - * Sets the entity that the camera should use the position and orientation from when it's in entity mode. You can also set - * the entity using the {@link Camera|Camera.cameraEntity} property. + * Sets the entity that the camera should follow (i.e., use the position and orientation from) when it's in entity mode. + * You can also set the entity using the {@link Camera|Camera.cameraEntity} property. * @function Camera.setCameraEntity * @param {Uuid} entityID - The entity that the camera should follow when it's in entity mode. * @example Move your camera to the position and orientation of the closest entity.