From ec86b82079eed8da622560c98e011bbaa69ff879 Mon Sep 17 00:00:00 2001
From: Ryan Huffman <ryanhuffman@gmail.com>
Date: Mon, 14 Nov 2016 12:14:24 -0800
Subject: [PATCH] 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<CameraMode>();
 
+/**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 <code>mode</code> 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 <code>position</code>. Only works while in <code>independent</code>.
+     * 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 <code>position</code>.
+     * 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: