Merge pull request #5132 from sebavan/master

Add more camera docs

src/Cameras/babylon.camera.ts

@@ -1,80 +1,81 @@
 module BABYLON {
+    /**
+     * This is the base class of all the camera used in the application.
+     * @see http://doc.babylonjs.com/features/cameras
+     */
     export class Camera extends Node {
-        public inputs: CameraInputsManager<Camera>;
-
-        // Statics
-        private static _PERSPECTIVE_CAMERA = 0;
-        private static _ORTHOGRAPHIC_CAMERA = 1;
-
-        private static _FOVMODE_VERTICAL_FIXED = 0;
-        private static _FOVMODE_HORIZONTAL_FIXED = 1;
-
-        private static _RIG_MODE_NONE = 0;
-        private static _RIG_MODE_STEREOSCOPIC_ANAGLYPH = 10;
-        private static _RIG_MODE_STEREOSCOPIC_SIDEBYSIDE_PARALLEL = 11;
-        private static _RIG_MODE_STEREOSCOPIC_SIDEBYSIDE_CROSSEYED = 12;
-        private static _RIG_MODE_STEREOSCOPIC_OVERUNDER = 13;
-        private static _RIG_MODE_VR = 20;
-        private static _RIG_MODE_WEBVR = 21;
-
-        public static get PERSPECTIVE_CAMERA(): number {
-            return Camera._PERSPECTIVE_CAMERA;
-        }
-
-        public static get ORTHOGRAPHIC_CAMERA(): number {
-            return Camera._ORTHOGRAPHIC_CAMERA;
-        }
+        /**
+         * This is the default projection mode used by the cameras.
+         * It helps recreating a feeling of perspective and better appreciate depth.
+         * This is the best way to simulate real life cameras.
+         */
+        public static readonly PERSPECTIVE_CAMERA = 0;
+        /**
+         * This helps creating camera with an orthographic mode.
+         * Orthographic is commonly used in engineering as a means to produce object specifications that communicate dimensions unambiguously, each line of 1 unit length (cm, meter..whatever) will appear to have the same length everywhere on the drawing. This allows the drafter to dimension only a subset of lines and let the reader know that other lines of that length on the drawing are also that length in reality. Every parallel line in the drawing is also parallel in the object.
+         */
+        public static readonly ORTHOGRAPHIC_CAMERA = 1;
 
         /**
          * This is the default FOV mode for perspective cameras.
          * This setting aligns the upper and lower bounds of the viewport to the upper and lower bounds of the camera frustum.
-         *
          */
-        public static get FOVMODE_VERTICAL_FIXED(): number {
-            return Camera._FOVMODE_VERTICAL_FIXED;
-        }
-
+        public static readonly FOVMODE_VERTICAL_FIXED = 0;
         /**
          * This setting aligns the left and right bounds of the viewport to the left and right bounds of the camera frustum.
-         *
          */
-        public static get FOVMODE_HORIZONTAL_FIXED(): number {
-            return Camera._FOVMODE_HORIZONTAL_FIXED;
-        }
-
-        public static get RIG_MODE_NONE(): number {
-            return Camera._RIG_MODE_NONE;
-        }
-
-        public static get RIG_MODE_STEREOSCOPIC_ANAGLYPH(): number {
-            return Camera._RIG_MODE_STEREOSCOPIC_ANAGLYPH;
-        }
-
-        public static get RIG_MODE_STEREOSCOPIC_SIDEBYSIDE_PARALLEL(): number {
-            return Camera._RIG_MODE_STEREOSCOPIC_SIDEBYSIDE_PARALLEL;
-        }
+        public static readonly FOVMODE_HORIZONTAL_FIXED = 1;
 
-        public static get RIG_MODE_STEREOSCOPIC_SIDEBYSIDE_CROSSEYED(): number {
-            return Camera._RIG_MODE_STEREOSCOPIC_SIDEBYSIDE_CROSSEYED;
-        }
-
-        public static get RIG_MODE_STEREOSCOPIC_OVERUNDER(): number {
-            return Camera._RIG_MODE_STEREOSCOPIC_OVERUNDER;
-        }
-
-        public static get RIG_MODE_VR(): number {
-            return Camera._RIG_MODE_VR;
-        }
-
-        public static get RIG_MODE_WEBVR(): number {
-            return Camera._RIG_MODE_WEBVR;
-        }
+        /**
+         * This specifies ther is no need for a camera rig.
+         * Basically only one eye is rendered corresponding to the camera.
+         */
+        public static readonly RIG_MODE_NONE = 0;
+        /**
+         * Simulates a camera Rig with one blue eye and one red eye.
+         * This can be use with 3d blue and red glasses.
+         */
+        public static readonly RIG_MODE_STEREOSCOPIC_ANAGLYPH = 10;
+        /**
+         * Defines that both eyes of the camera will be rendered side by side with a parallel target.
+         */
+        public static readonly RIG_MODE_STEREOSCOPIC_SIDEBYSIDE_PARALLEL = 11;
+        /**
+         * Defines that both eyes of the camera will be rendered side by side with a none parallel target.
+         */
+        public static readonly RIG_MODE_STEREOSCOPIC_SIDEBYSIDE_CROSSEYED = 12;
+        /**
+         * Defines that both eyes of the camera will be rendered over under each other.
+         */
+        public static readonly RIG_MODE_STEREOSCOPIC_OVERUNDER = 13;
+        /**
+         * Defines that both eyes of the camera should be renderered in a VR mode (carbox).
+         */
+        public static readonly RIG_MODE_VR = 20;
+        /**
+         * Defines that both eyes of the camera should be renderered in a VR mode (webVR).
+         */
+        public static readonly RIG_MODE_WEBVR = 21;
 
+        /**
+         * Defines if by default attaching controls should prevent the default javascript event to continue.
+         */
         public static ForceAttachControlToAlwaysPreventDefault = false;
 
+        /**
+         * @hidden
+         * Might be removed once multiview will be a thing
+         */
         public static UseAlternateWebVRRendering = false;
 
-        // Members
+        /**
+         * Define the input manager associated with the camera.
+         */
+        public inputs: CameraInputsManager<Camera>;
+
+        /**
+         * Define the current local position of the camera in the scene
+         */
         @serializeAsVector3()
         public position: Vector3;
 
@@ -85,37 +86,79 @@
         @serializeAsVector3()
         public upVector = Vector3.Up();
 
+        /**
+         * Define the current limit on the left side for an orthographic camera
+         * In scene unit
+         */
         @serialize()
         public orthoLeft: Nullable<number> = null;
 
+        /**
+         * Define the current limit on the right side for an orthographic camera
+         * In scene unit
+         */
         @serialize()
         public orthoRight: Nullable<number> = null;
 
+        /**
+         * Define the current limit on the bottom side for an orthographic camera
+         * In scene unit
+         */
         @serialize()
         public orthoBottom: Nullable<number> = null;
 
+        /**
+         * Define the current limit on the top side for an orthographic camera
+         * In scene unit
+         */
         @serialize()
         public orthoTop: Nullable<number> = null;
 
         /**
-         * FOV is set in Radians. (default is 0.8)
+         * Field Of View is set in Radians. (default is 0.8)
          */
         @serialize()
         public fov = 0.8;
 
+        /**
+         * Define the minimum distance the camera can see from.
+         * This is important to note that the depth buffer are not infinite and the closer it starts 
+         * the more your scene might encounter depth fighting issue.
+         */
         @serialize()
         public minZ = 1;
 
+        /**
+         * Define the maximum distance the camera can see to.
+         * This is important to note that the depth buffer are not infinite and the further it end 
+         * the more your scene might encounter depth fighting issue.
+         */
         @serialize()
         public maxZ = 10000.0;
 
+        /**
+         * Define the default inertia of the camera.
+         * This helps giving a smooth feeling to the camera movment.
+         */
         @serialize()
         public inertia = 0.9;
 
+        /**
+         * Define the mode of the camera (Camera.PERSPECTIVE_CAMERA or Camera.PERSPECTIVE_ORTHOGRAPHIC)
+         */
         @serialize()
         public mode = Camera.PERSPECTIVE_CAMERA;
+
+        /**
+         * Define wether the camera is intermediate.
+         * This is usefull to not present the output directly to the screen in case of rig without post process for instance
+         */
         public isIntermediate = false;
 
+        /**
+         * Define the viewport of the camera.
+         * This correspond to the portion of the screen the camera will render to in normalized 0 to 1 unit.
+         */
         public viewport = new Viewport(0, 0, 1.0, 1.0);
 
         /**
@@ -131,16 +174,50 @@
         @serialize()
         public fovMode: number = Camera.FOVMODE_VERTICAL_FIXED;
 
-        // Camera rig members
+        /**
+         * Rig mode of the camera.
+         * This is usefull to create the camera with two "eyes" instead of one to create VR or stereoscopic scenes.
+         * This is normally controlled byt the camera themselves as internal use.
+         */
         @serialize()
         public cameraRigMode = Camera.RIG_MODE_NONE;
 
+        /**
+         * Defines the distance between both "eyes" in case of a RIG
+         */
         @serialize()
         public interaxialDistance: number
 
+        /**
+         * Defines if stereoscopic rendering is done side by side or over under.
+         */
         @serialize()
         public isStereoscopicSideBySide: boolean
 
+        /**
+         * Defines the list of custom render target the camera should render to.
+         * This is pretty helpfull if you wish to make a camera render to a texture you could reuse somewhere 
+         * else in the scene.
+         */
+        public customRenderTargets = new Array<RenderTargetTexture>();
+
+        /**
+         * Observable triggered when the camera view matrix has changed.
+         */
+        public onViewMatrixChangedObservable = new Observable<Camera>();
+        /**
+         * Observable triggered when the camera Projection matrix has changed.
+         */
+        public onProjectionMatrixChangedObservable = new Observable<Camera>();
+        /**
+         * Observable triggered when the inputs have been processed.
+         */
+        public onAfterCheckInputsObservable = new Observable<Camera>();
+        /**
+         * Observable triggered when reset has been called and applied to the camera.
+         */
+        public onRestoreStateObservable = new Observable<Camera>();
+
         /** @hidden */
         public _cameraRigParams: any;
         /** @hidden */
@@ -154,27 +231,34 @@
         /** @hidden */
         public _alternateCamera: Camera;
 
-        public customRenderTargets = new Array<RenderTargetTexture>();
-
-        // Observables
-        public onViewMatrixChangedObservable = new Observable<Camera>();
-        public onProjectionMatrixChangedObservable = new Observable<Camera>();
-        public onAfterCheckInputsObservable = new Observable<Camera>();
-        public onRestoreStateObservable = new Observable<Camera>();
-
-        // Cache
-        private _computedViewMatrix = Matrix.Identity();
+        /** @hidden */
         public _projectionMatrix = new Matrix();
-        private _doNotComputeProjectionMatrix = false;
+
+        /** @hidden */
         public _postProcesses = new Array<Nullable<PostProcess>>();
-        private _transformMatrix = Matrix.Zero();
 
+        /** @hidden */
         public _activeMeshes = new SmartArray<AbstractMesh>(256);
 
         protected _globalPosition = Vector3.Zero();
+
+        private _computedViewMatrix = Matrix.Identity();
+        private _doNotComputeProjectionMatrix = false;
+        private _transformMatrix = Matrix.Zero();
         private _frustumPlanes: Plane[];
         private _refreshFrustumPlanes = true;
+        private _storedFov: number;
+        private _stateStored: boolean;
 
+        /**
+         * Instantiates a new camera object.
+         * This should not be used directly but through the inherited cameras: ArcRotate, Free...
+         * @see http://doc.babylonjs.com/features/cameras
+         * @param name Defines the name of the camera in the scene
+         * @param position Defines the position of the camera
+         * @param scene Defines the scene the camera belongs too
+         * @param setActiveOnSceneIfNoneActive Defines if the camera should be set as active after creation if no other camera have been defined in the scene
+         */
         constructor(name: string, position: Vector3, scene: Scene, setActiveOnSceneIfNoneActive = true) {
             super(name, scene);
 
@@ -187,11 +271,9 @@
             this.position = position;
         }
 
-        private _storedFov: number;
-        private _stateStored: boolean;
-
         /**
          * Store current camera state (fov, position, etc..)
+         * @returns the camera
          */
         public storeState(): Camera {
             this._stateStored = true;
@@ -214,7 +296,8 @@
         }
 
         /**
-         * Restored camera state. You must call storeState() first
+         * Restored camera state. You must call storeState() first.
+         * @returns true if restored and false otherwise
          */
         public restoreState(): boolean {
             if (this._restoreStateValues()) {
@@ -225,12 +308,18 @@
             return false;
         }
 
+        /**
+         * Gets the class name of the camera.
+         * @returns the class name
+         */
         public getClassName(): string {
             return "Camera";
         }
 
         /**
-         * @param {boolean} fullDetails - support for multiple levels of logging within scene loading
+         * Gets a string representation of the camera usefull for debug purpose.
+         * @param fullDetails Defines that a more verboe level of logging is required
+         * @returns the string representation
          */
         public toString(fullDetails?: boolean): string {
             var ret = "Name: " + this.name;
@@ -245,14 +334,26 @@
             return ret;
         }
 
+        /**
+         * Gets the current world space position of the camera.
+         */
         public get globalPosition(): Vector3 {
             return this._globalPosition;
         }
 
+        /**
+         * Gets the list of active meshes this frame (meshes no culled or excluded by lod s in the frame)
+         * @returns the active meshe list
+         */
         public getActiveMeshes(): SmartArray<AbstractMesh> {
             return this._activeMeshes;
         }
 
+        /**
+         * Check wether a mesh is part of the current active mesh list of the camera
+         * @param mesh Defines the mesh to check 
+         * @returns true if active, false otherwise
+         */
         public isActiveMesh(mesh: Mesh): boolean {
             return (this._activeMeshes.indexOf(mesh) !== -1);
         }
@@ -273,7 +374,6 @@
             return super.isReady(completeCheck);
         }
 
-        //Cache
         /** @hidden */
         public _initCache() {
             super._initCache();
@@ -307,7 +407,6 @@
             this._cache.upVector.copyFrom(this.upVector);
         }
 
-        // Synchronized
         /** @hidden */
         public _isSynchronized(): boolean {
             return this._isSynchronizedViewMatrix() && this._isSynchronizedProjectionMatrix();
@@ -352,13 +451,24 @@
             return check;
         }
 
-        // Controls
+        /**
+         * Attach the input controls to a specific dom element to get the input from.
+         * @param element Defines the element the controls should be listened from
+         * @param noPreventDefault Defines whether event caught by the controls should call preventdefault() (https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault)
+         */
         public attachControl(element: HTMLElement, noPreventDefault?: boolean): void {
         }
 
+        /**
+         * Detach the current controls from the specified dom element.
+         * @param element Defines the element to stop listening the inputs from
+         */
         public detachControl(element: HTMLElement): void {
         }
 
+        /**
+         * Update the camera state according to the different inputs gathered during the frame.
+         */
         public update(): void {
             this._checkInputs();
             if (this.cameraRigMode !== Camera.RIG_MODE_NONE) {
@@ -371,6 +481,7 @@
             this.onAfterCheckInputsObservable.notifyObservers(this);
         }
 
+        /** @hidden */
         public get rigCameras(): Camera[] {
             return this._rigCameras;
         }
@@ -420,6 +531,13 @@
             }
         }
 
+        /**
+         * Attach a post process to the camera.
+         * @see http://doc.babylonjs.com/how_to/how_to_use_postprocesses#attach-postprocess
+         * @param postProcess The post process to attach to the camera
+         * @param insertAt The position of the post process in case several of them are in use in the scene
+         * @returns the position the post process has been inserted at
+         */
         public attachPostProcess(postProcess: PostProcess, insertAt: Nullable<number> = null): number {
             if (!postProcess.isReusable() && this._postProcesses.indexOf(postProcess) > -1) {
                 Tools.Error("You're trying to reuse a post process not defined as reusable.");
@@ -437,6 +555,11 @@
             return this._postProcesses.indexOf(postProcess);
         }
 
+        /**
+         * Detach a post process to the camera.
+         * @see http://doc.babylonjs.com/how_to/how_to_use_postprocesses#attach-postprocess
+         * @param postProcess The post process to detach from the camera
+         */
         public detachPostProcess(postProcess: PostProcess): void {
             var idx = this._postProcesses.indexOf(postProcess);
             if (idx !== -1) {
@@ -445,6 +568,9 @@
             this._cascadePostProcessesToRigCams(); // also ensures framebuffer invalidated
         }
 
+        /**
+         * Gets the current world matrix of the camera
+         */
         public getWorldMatrix(): Matrix {
             if (this._isSynchronizedViewMatrix()) {
                 return this._worldMatrix;
@@ -457,10 +583,15 @@
         }
 
         /** @hidden */
-        public _getViewMatrix(): Matrix {
+        protected _getViewMatrix(): Matrix {
             return Matrix.Identity();
         }
 
+        /**
+         * Gets the current view matrix of the camera.
+         * @param force forces the camera to recompute the matrix without looking at the cached state
+         * @returns the view matrix
+         */
         public getViewMatrix(force?: boolean): Matrix {
             if (!force && this._isSynchronizedViewMatrix()) {
                 return this._computedViewMatrix;
@@ -484,7 +615,12 @@
             return this._computedViewMatrix;
         }
 
-
+        /**
+         * Freeze the projection matrix.
+         * It will prevent the cache check of the camera projection compute and can speed up perf 
+         * if no parameter of the camera are meant to change
+         * @param projection Defines manually a projection if necessary
+         */
         public freezeProjectionMatrix(projection?: Matrix): void {
             this._doNotComputeProjectionMatrix = true;
             if (projection !== undefined) {
@@ -492,10 +628,18 @@
             }
         };
 
+        /**
+         * Unfreeze the projection matrix if it has previously been freezed by freezeProjectionMatrix.
+         */
         public unfreezeProjectionMatrix(): void {
             this._doNotComputeProjectionMatrix = false;
         };
 
+        /**
+         * Gets the current projection matrix of the camera.
+         * @param force forces the camera to recompute the matrix without looking at the cached state
+         * @returns the projection matrix
+         */
         public getProjectionMatrix(force?: boolean): Matrix {
             if (this._doNotComputeProjectionMatrix || (!force && this._isSynchronizedProjectionMatrix())) {
                 return this._projectionMatrix;
@@ -578,7 +722,7 @@
             return this._transformMatrix;
         }
 
-        private updateFrustumPlanes(): void {
+        private _updateFrustumPlanes(): void {
             if (!this._refreshFrustumPlanes) {
                 return;
             }
@@ -594,18 +738,37 @@
             this._refreshFrustumPlanes = false;
         }
 
+        /**
+         * Checks if a cullable object (mesh...) is in the camera frustum
+         * This checks the bounding box center. See isCompletelyInFrustum for a full bounding check
+         * @param target The object to check
+         * @returns true if the object is in frustum otherwise false
+         */
         public isInFrustum(target: ICullable): boolean {
-            this.updateFrustumPlanes();
+            this._updateFrustumPlanes();
 
             return target.isInFrustum(this._frustumPlanes);
         }
 
+        /**
+         * Checks if a cullable object (mesh...) is in the camera frustum
+         * Unlike isInFrustum this cheks the full bounding box
+         * @param target The object to check
+         * @returns true if the object is in frustum otherwise false
+         */
         public isCompletelyInFrustum(target: ICullable): boolean {
-            this.updateFrustumPlanes();
+            this._updateFrustumPlanes();
 
             return target.isCompletelyInFrustum(this._frustumPlanes);
         }
 
+        /**
+         * Gets a ray in the forward direction from the camera.
+         * @param length Defines the length of the ray to create
+         * @param transform Defines the transform to apply to the ray, by default the world matrx is used to create a workd space ray
+         * @param origin Defines the start point of the ray which defaults to the camera position
+         * @returns the forward ray
+         */
         public getForwardRay(length = 100, transform?: Matrix, origin?: Vector3): Ray {
             if (!transform) {
                 transform = this.getWorldMatrix();
@@ -683,7 +846,9 @@
             super.dispose(doNotRecurse, disposeMaterialAndTextures);
         }
 
-        // ---- Camera rigs section ----
+        /**
+         * Gets the left camera of a rig setup in case of Rigged Camera
+         */
         public get leftCamera(): Nullable<FreeCamera> {
             if (this._rigCameras.length < 1) {
                 return null;
@@ -691,6 +856,9 @@
             return (<FreeCamera>this._rigCameras[0]);
         }
 
+        /**
+         * Gets the right camera of a rig setup in case of Rigged Camera
+         */
         public get rightCamera(): Nullable<FreeCamera> {
             if (this._rigCameras.length < 2) {
                 return null;
@@ -698,6 +866,10 @@
             return (<FreeCamera>this._rigCameras[1]);
         }
 
+        /**
+         * Gets the left camera target of a rig setup in case of Rigged Camera
+         * @returns the target position
+         */
         public getLeftTarget(): Nullable<Vector3> {
             if (this._rigCameras.length < 1) {
                 return null;
@@ -705,6 +877,10 @@
             return (<TargetCamera>this._rigCameras[0]).getTarget();
         }
 
+        /**
+         * Gets the right camera target of a rig setup in case of Rigged Camera
+         * @returns the target position
+         */
         public getRightTarget(): Nullable<Vector3> {
             if (this._rigCameras.length < 2) {
                 return null;
@@ -712,6 +888,9 @@
             return (<TargetCamera>this._rigCameras[1]).getTarget();
         }
 
+        /**
+         * @hidden
+         */
         public setCameraRigMode(mode: number, rigParams: any): void {
             if (this.cameraRigMode === mode) {
                 return;
@@ -850,6 +1029,7 @@
             return Matrix.Identity();
         }
 
+        /** @hidden */
         public setCameraRigParameter(name: string, value: any) {
             if (!this._cameraRigParams) {
                 this._cameraRigParams = {};
@@ -863,6 +1043,7 @@
 
         /**
          * needs to be overridden by children so sub has required properties to be copied
+         * @hidden
          */
         public createRigCamera(name: string, cameraIndex: number): Nullable<Camera> {
             return null;
@@ -889,6 +1070,10 @@
         public _setupInputs() {
         }
 
+        /**
+         * Serialiaze the camera setup to a json represention
+         * @returns the JSON representation
+         */
         public serialize(): any {
             var serializationObject = SerializationHelper.Serialize(this);
 
@@ -910,10 +1095,20 @@
             return serializationObject;
         }
 
+        /**
+         * Clones the current camera.
+         * @param name The cloned camera name
+         * @returns the cloned camera
+         */
         public clone(name: string): Camera {
             return SerializationHelper.Clone(Camera.GetConstructorFromName(this.getClassName(), name, this.getScene(), this.interaxialDistance, this.isStereoscopicSideBySide), this);
         }
 
+        /**
+         * Gets the direction of the camera relative to a given local axis.
+         * @param localAxis Defines the reference axis to provide a relative direction.
+         * @return the direction
+         */
         public getDirection(localAxis: Vector3): Vector3 {
             var result = Vector3.Zero();
 
@@ -922,10 +1117,24 @@
             return result;
         }
 
+        /**
+         * Gets the direction of the camera relative to a given local axis into a passed vector.
+         * @param localAxis Defines the reference axis to provide a relative direction.
+         * @param result Defines the vector to store the result in
+         */
         public getDirectionToRef(localAxis: Vector3, result: Vector3): void {
             Vector3.TransformNormalToRef(localAxis, this.getWorldMatrix(), result);
         }
 
+        /**
+         * Gets a camera constructor for a given camera type
+         * @param type The type of the camera to construct (should be equal to one of the camera class name)
+         * @param name The name of the camera the result will be able to instantiate
+         * @param scene The scene the result will construct the camera in
+         * @param interaxial_distance In case of stereoscopic setup, the distance between both eyes
+         * @param isStereoscopicSideBySide In case of stereoscopic setup, should the sereo be side b side
+         * @returns a factory method to construc the camera
+         */
         static GetConstructorFromName(type: string, name: string, scene: Scene, interaxial_distance: number = 0, isStereoscopicSideBySide: boolean = true): () => Camera {
             let constructorFunc = Node.Construct(type, name, scene, {
                 interaxial_distance: interaxial_distance,
@@ -940,10 +1149,20 @@
             return () => new UniversalCamera(name, Vector3.Zero(), scene);
         }
 
+        /**
+         * Compute the world  matrix of the camera.
+         * @returns the camera workd matrix
+         */
         public computeWorldMatrix(): Matrix {
             return this.getWorldMatrix();
         }
 
+        /**
+         * Parse a JSON and creates the camera from the parsed information
+         * @param parsedCamera The JSON to parse
+         * @param scene The scene to instantiate the camera in
+         * @returns the newly constructed camera
+         */
         public static Parse(parsedCamera: any, scene: Scene): Camera {
             var type = parsedCamera.type;
             var construct = Camera.GetConstructorFromName(type, parsedCamera.name, scene, parsedCamera.interaxial_distance, parsedCamera.isStereoscopicSideBySide);

src/Cameras/babylon.followCamera.ts

@@ -7,36 +7,64 @@
         return () => new ArcFollowCamera(name, 0, 0, 1.0, null, scene);
     });
 
+    /**
+     * A follow camera takes a mesh as a target and follows it as it moves. Both a free camera version followCamera and 
+     * an arc rotate version arcFollowCamera are available.
+     * @see http://doc.babylonjs.com/features/cameras#follow-camera
+     */
     export class FollowCamera extends TargetCamera {
+        /**
+         * Distance the follow camera should follow an object at
+         */
         @serialize()
         public radius: number = 12;
 
+        /**
+         * Define a rotation offset between the camera and the object it follows
+         */
         @serialize()
         public rotationOffset: number = 0;
 
+        /**
+         * Define a height offset between the camera and the object it follows.
+         * It can help following an object from the top (like a car chaing a plane)
+         */
         @serialize()
         public heightOffset: number = 4;
 
+        /**
+         * Define how fast the camera can accelerate to follow it s target.
+         */
         @serialize()
         public cameraAcceleration: number = 0.05;
 
+        /**
+         * Define the speed limit of the camera following an object.
+         */
         @serialize()
         public maxCameraSpeed: number = 20;
 
+        /**
+         * Define the target of the camera.
+         */
         @serializeAsMeshReference("lockedTargetId")
         public lockedTarget: Nullable<AbstractMesh>;
 
+        /**
+         * Instantiates the follow camera.
+         * @see http://doc.babylonjs.com/features/cameras#follow-camera
+         * @param name Define the name of the camera in the scene
+         * @param position Define the position of the camera
+         * @param scene Define the scene the camera belong to
+         * @param lockedTarget Define the target of the camera
+         */
         constructor(name: string, position: Vector3, scene: Scene, lockedTarget: Nullable<AbstractMesh> = null) {
             super(name, position, scene);
 
             this.lockedTarget = lockedTarget;
         }
 
-        private getRadians(degrees: number): number {
-            return degrees * Math.PI / 180;
-        }
-
-        private follow(cameraTarget: AbstractMesh) {
+        private _follow(cameraTarget: AbstractMesh) {
             if (!cameraTarget)
                 return;
 
@@ -48,7 +76,7 @@
             } else {
                 yRotation = cameraTarget.rotation.y;
             }
-            var radians = this.getRadians(this.rotationOffset) + yRotation;
+            var radians = Tools.ToRadians(this.rotationOffset) + yRotation;
             var targetPosition = cameraTarget.getAbsolutePosition();
             var targetX: number = targetPosition.x + Math.sin(radians) * this.radius;
 
@@ -80,10 +108,14 @@
         public _checkInputs(): void {
             super._checkInputs();
             if (this.lockedTarget) {
-                this.follow(this.lockedTarget);
+                this._follow(this.lockedTarget);
             }
         }
 
+        /**
+         * Gets the camera class name.
+         * @returns the class name
+         */
         public getClassName(): string {
             return "FollowCamera";
         }
@@ -91,7 +123,8 @@
 
     /**
      * Arc Rotate version of the follow camera.
-     * It still follows a defined mesh but in an Arc Rotate Camera fashion.
+     * It still follows a Defined mesh but in an Arc Rotate Camera fashion.
+     * @see http://doc.babylonjs.com/features/cameras#follow-camera
      */
     export class ArcFollowCamera extends TargetCamera {
 
@@ -99,12 +132,13 @@
 
         /**
          * Instantiates a new ArcFollowCamera
-         * @param name Defines the name of the camera
-         * @param alpha Defines the rotation angle of the camera around the logitudinal axis
-         * @param beta Defines the rotation angle of the camera around the elevation axis
-         * @param radius Defines the radius of the camera from its target point
-         * @param target Defines the target of the camera
-         * @param scene Defines the scene the camera belongs to
+         * @see http://doc.babylonjs.com/features/cameras#follow-camera
+         * @param name Define the name of the camera
+         * @param alpha Define the rotation angle of the camera around the logitudinal axis
+         * @param beta Define the rotation angle of the camera around the elevation axis
+         * @param radius Define the radius of the camera from its target point
+         * @param target Define the target of the camera
+         * @param scene Define the scene the camera belongs to
          */
         constructor(name: string, 
             /** The longitudinal angle of the camera */
@@ -113,14 +147,14 @@
             public beta: number, 
             /** The radius of the camera from its target */
             public radius: number, 
-            /** Defines the camera target (the messh it should follow) */
+            /** Define the camera target (the messh it should follow) */
             public target: Nullable<AbstractMesh>, 
             scene: Scene) {
             super(name, Vector3.Zero(), scene);
-            this.follow();
+            this._follow();
         }
 
-        private follow(): void {
+        private _follow(): void {
             if (!this.target) {
                 return;
             }
@@ -136,7 +170,7 @@
         /** @hidden */
         public _checkInputs(): void {
             super._checkInputs();
-            this.follow();
+            this._follow();
         }
 
         /**

src/Cameras/babylon.freeCamera.ts

@@ -4,22 +4,45 @@
         return () => new UniversalCamera(name, Vector3.Zero(), scene);
     });
 
+    /**
+     * This represents a free type of camera. It can be usefull in First Person Shooter game for instance.
+     * Please consider using the new UniversalCamera instead as it adds more functionality like the gamepad.
+     * @see http://doc.babylonjs.com/features/cameras#universal-camera
+     */
     export class FreeCamera extends TargetCamera {
+        /**
+         * Define the collision ellipsoid of the camera.
+         * This is helpful to simulate a camera body like the player body around the camera
+         * @see http://doc.babylonjs.com/babylon101/cameras,_mesh_collisions_and_gravity#arcrotatecamera
+         */
         @serializeAsVector3()
         public ellipsoid = new Vector3(0.5, 1, 0.5);
 
+        /**
+         * Define an offset for the position of the ellipsoid around the camera.
+         * This can be helpful to determine the center of the body near the gravity center of the body 
+         * instead of its head.
+         */
         @serializeAsVector3()
         public ellipsoidOffset = new Vector3(0, 0, 0);
 
+        /**
+         * Enable or disable collisions of the camera with the rest of the scene objects.
+         */
         @serialize()
         public checkCollisions = false;
 
+        /**
+         * Enable or disable gravity on the camera.
+         */
         @serialize()
         public applyGravity = false;
 
+        /**
+         * Define the input manager associated to the camera.
+         */
         public inputs: FreeCameraInputsManager;
 
-        //-- begin properties for backward compatibility for inputs
         /**
          * Gets the input sensibility for a mouse input. (default is 2000.0)
          * Higher values reduce sensitivity.
@@ -42,6 +65,9 @@
                 mouse.angularSensibility = value;
         }
 
+        /**
+         * Gets or Set the list of keyboard keys used to control the forward move of the camera.
+         */
         public get keysUp(): number[] {
             var keyboard = <FreeCameraKeyboardMoveInput>this.inputs.attached["keyboard"];
             if (keyboard)
@@ -56,6 +82,9 @@
                 keyboard.keysUp = value;
         }
 
+        /**
+         * Gets or Set the list of keyboard keys used to control the backward move of the camera.
+         */
         public get keysDown(): number[] {
             var keyboard = <FreeCameraKeyboardMoveInput>this.inputs.attached["keyboard"];
             if (keyboard)
@@ -70,6 +99,9 @@
                 keyboard.keysDown = value;
         }
 
+        /**
+         * Gets or Set the list of keyboard keys used to control the left strafe move of the camera.
+         */
         public get keysLeft(): number[] {
             var keyboard = <FreeCameraKeyboardMoveInput>this.inputs.attached["keyboard"];
             if (keyboard)
@@ -84,6 +116,9 @@
                 keyboard.keysLeft = value;
         }
 
+        /**
+         * Gets or Set the list of keyboard keys used to control the right strafe move of the camera.
+         */
         public get keysRight(): number[] {
             var keyboard = <FreeCameraKeyboardMoveInput>this.inputs.attached["keyboard"];
             if (keyboard)
@@ -98,8 +133,9 @@
                 keyboard.keysRight = value;
         }
 
-        //-- end properties for backward compatibility for inputs
-
+        /**
+         * Event raised when the camera collide with a mesh in the scene.
+         */
         public onCollide: (collidedMesh: AbstractMesh) => void;
 
         private _collider: Collider;
@@ -113,17 +149,36 @@
         /** @hidden */
         public _transformedDirection: Vector3;
 
+        /**
+         * Instantiates a Free Camera.
+         * This represents a free type of camera. It can be usefull in First Person Shooter game for instance.
+         * Please consider using the new UniversalCamera instead as it adds more functionality like touch to this camera.
+         * @see http://doc.babylonjs.com/features/cameras#universal-camera
+         * @param name Define the name of the camera in the scene
+         * @param position Define the start position of the camera in the scene
+         * @param scene Define the scene the camera belongs to
+         * @param setActiveOnSceneIfNoneActive Defines wheter the camera should be marked as active if not other active cameras have been defined
+         */
         constructor(name: string, position: Vector3, scene: Scene, setActiveOnSceneIfNoneActive = true) {
             super(name, position, scene, setActiveOnSceneIfNoneActive);
             this.inputs = new FreeCameraInputsManager(this);
             this.inputs.addKeyboard().addMouse();
         }
 
-        // Controls
+        /**
+         * Attached controls to the current camera.
+         * @param element Defines the element the controls should be listened from
+         * @param noPreventDefault Defines whether event caught by the controls should call preventdefault() (https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault)
+         */
         public attachControl(element: HTMLElement, noPreventDefault?: boolean): void {
             this.inputs.attachElement(element, noPreventDefault);
         }
 
+        /**
+         * Detach the current controls from the camera.
+         * The camera will stop reacting to inputs.
+         * @param element Defines the element to stop listening the inputs from
+         */
         public detachControl(element: HTMLElement): void {
             this.inputs.detachElement(element);
 
@@ -134,6 +189,9 @@
         // Collisions
         private _collisionMask = -1;
 
+        /**
+         * Define a collision mask to limit the list of object the camera can collide with
+         */
         public get collisionMask(): number {
             return this._collisionMask;
         }
@@ -222,11 +280,18 @@
             }
         }
 
+        /**
+         * Destroy the camera and release the current resources hold by it.
+         */
         public dispose(): void {
             this.inputs.clear();
             super.dispose();
         }
 
+        /**
+         * Gets the current object class name.
+         * @return the class name
+         */
         public getClassName(): string {
             return "FreeCamera";
         }

src/Cameras/babylon.freeCameraInputsManager.ts

@@ -1,29 +1,58 @@
 module BABYLON {
+    /**
+     * Default Inputs manager for the FreeCamera.
+     * It groups all the default supported inputs for ease of use.
+     * @see http://doc.babylonjs.com/how_to/customizing_camera_inputs
+     */
     export class FreeCameraInputsManager extends CameraInputsManager<FreeCamera> {
+        /**
+         * Instantiates a new FreeCameraInputsManager.
+         * @param camera Defines the camera the inputs belong to
+         */
         constructor(camera: FreeCamera) {
             super(camera);
         }
 
+        /**
+         * Add keyboard input support to the input manager.
+         * @returns the current input manager
+         */
         addKeyboard(): FreeCameraInputsManager {
             this.add(new FreeCameraKeyboardMoveInput());
             return this;
         }
 
+        /**
+         * Add mouse input support to the input manager.
+         * @returns the current input manager
+         */
         addMouse(touchEnabled = true): FreeCameraInputsManager {
             this.add(new FreeCameraMouseInput(touchEnabled));
             return this;
         }
 
+        /**
+         * Add orientation input support to the input manager.
+         * @returns the current input manager
+         */
         addDeviceOrientation(): FreeCameraInputsManager {
             this.add(new FreeCameraDeviceOrientationInput());
             return this;
         }
 
+        /**
+         * Add touch input support to the input manager.
+         * @returns the current input manager
+         */
         addTouch(): FreeCameraInputsManager {
             this.add(new FreeCameraTouchInput());
             return this;
         }
 
+        /**
+         * Add virtual joystick input support to the input manager.
+         * @returns the current input manager
+         */
         addVirtualJoystick(): FreeCameraInputsManager {
             this.add(new FreeCameraVirtualJoystickInput());
             return this;

src/Cameras/babylon.gamepadCamera.ts

@@ -3,43 +3,29 @@ module BABYLON {
         return () => new GamepadCamera(name, Vector3.Zero(), scene);
     });
 
-    // We're mainly based on the logic defined into the FreeCamera code
+    /**
+     * This represents a FPS type of camera. This is only here for back compat purpose.
+     * Please use the UniversalCamera instead as both are identical.
+     * @see http://doc.babylonjs.com/features/cameras#universal-camera
+     */
     export class GamepadCamera extends UniversalCamera {
-        //-- Begin properties for backward compatibility for inputs
-        public get gamepadAngularSensibility(): number {
-            var gamepad = <FreeCameraGamepadInput>this.inputs.attached["gamepad"];
-            if (gamepad)
-                return gamepad.gamepadAngularSensibility;
-
-            return 0;
-        }
-
-        public set gamepadAngularSensibility(value: number) {
-            var gamepad = <FreeCameraGamepadInput>this.inputs.attached["gamepad"];
-            if (gamepad)
-                gamepad.gamepadAngularSensibility = value;
-        }
-
-        public get gamepadMoveSensibility(): number {
-            var gamepad = <FreeCameraGamepadInput>this.inputs.attached["gamepad"];
-            if (gamepad)
-                return gamepad.gamepadMoveSensibility;
-
-            return 0;
-        }
-
-        public set gamepadMoveSensibility(value: number) {
-            var gamepad = <FreeCameraGamepadInput>this.inputs.attached["gamepad"];
-            if (gamepad)
-                gamepad.gamepadMoveSensibility = value;
-        }
-        //-- end properties for backward compatibility for inputs
-
-
+        /**
+         * Instantiates a new Gamepad Camera
+         * This represents a FPS type of camera. This is only here for back compat purpose.
+         * Please use the UniversalCamera instead as both are identical.
+         * @see http://doc.babylonjs.com/features/cameras#universal-camera
+         * @param name Define the name of the camera in the scene
+         * @param position Define the start position of the camera in the scene
+         * @param scene Define the scene the camera belongs to
+         */
         constructor(name: string, position: Vector3, scene: Scene) {
             super(name, position, scene);
         }
 
+        /**
+         * Gets the current object class name.
+         * @return the class name
+         */
         public getClassName(): string {
             return "GamepadCamera";
         }

src/Cameras/babylon.targetCamera.ts

@@ -1,19 +1,46 @@
 module BABYLON {
+    /**
+     * A target camera takes a mesh or position as a target and continues to look at it while it moves. 
+     * This is the base of the follow, arc rotate cameras and Free camera
+     * @see http://doc.babylonjs.com/features/cameras
+     */
     export class TargetCamera extends Camera {
 
+        /**
+         * Define the current direction the camera is moving to
+         */
         public cameraDirection = new Vector3(0, 0, 0);
+        /**
+         * Define the current rotation the camera is rotating to
+         */
         public cameraRotation = new Vector2(0, 0);
 
+        /**
+         * Define the current rotation of the camera
+         */
         @serializeAsVector3()
         public rotation = new Vector3(0, 0, 0);
 
+        /**
+         * Define the current rotation of the camera as a quaternion to prevent Gimbal lock
+         */
         public rotationQuaternion: Quaternion;
 
+        /**
+         * Define the current speed of the camera
+         */
         @serialize()
         public speed = 2.0;
 
+        /**
+         * Add cconstraint to the camera to prevent it to move freely in all directions and
+         * around all axis.
+         */
         public noRotationConstraint = false;
 
+        /**
+         * Define the current target of the camera as an object or a position.
+         */
         @serializeAsMeshReference("lockedTargetId")
         public lockedTarget: any = null;
 
@@ -42,10 +69,24 @@
 
         private _defaultUp = BABYLON.Vector3.Up();
 
+        /**
+         * Instantiates a target camera that takes a meshor position as a target and continues to look at it while it moves. 
+         * This is the base of the follow, arc rotate cameras and Free camera
+         * @see http://doc.babylonjs.com/features/cameras
+         * @param name Defines the name of the camera in the scene
+         * @param position Defines the start position of the camera in the scene
+         * @param scene Defines the scene the camera belongs to
+         * @param setActiveOnSceneIfNoneActive Defines wheter the camera should be marked as active if not other active cameras have been defined
+         */
         constructor(name: string, position: Vector3, scene: Scene, setActiveOnSceneIfNoneActive = true) {
             super(name, position, scene, setActiveOnSceneIfNoneActive);
         }
 
+        /**
+         * Gets the position in front of the camera at a given distance.
+         * @param distance The distance from the camera we want the position to be
+         * @returns the position
+         */
         public getFrontPosition(distance: number): Vector3 {
             this.getWorldMatrix();
             var direction = this.getTarget().subtract(this.position);
@@ -67,15 +108,14 @@
             return this.lockedTarget.absolutePosition || this.lockedTarget;
         }
 
-        // State
-
-        /**
-         * Store current camera state (fov, position, etc..)
-         */
         private _storedPosition: Vector3;
         private _storedRotation: Vector3;
         private _storedRotationQuaternion: Quaternion;
 
+        /**
+         * Store current camera state of the camera (fov, position, rotation, etc..)
+         * @returns the camera
+         */
         public storeState(): Camera {
             this._storedPosition = this.position.clone();
             this._storedRotation = this.rotation.clone();
@@ -109,7 +149,6 @@
             return true;
         }
 
-        // Cache
         /** @hidden */
         public _initCache() {
             super._initCache();
@@ -206,6 +245,7 @@
 
         /**
          * Return the current target position of the camera. This value is expressed in local space.
+         * @returns the target position
          */
         public getTarget(): Vector3 {
             return this._currentTarget;
@@ -355,8 +395,7 @@
         }
 
         /**
-         * @override
-         * Override Camera.createRigCamera
+         * @hidden
          */
         public createRigCamera(name: string, cameraIndex: number): Nullable<Camera> {
             if (this.cameraRigMode !== Camera.RIG_MODE_NONE) {
@@ -375,8 +414,6 @@
 
         /**
          * @hidden
-         * @override
-         * Override Camera._updateRigCameras
          */
         public _updateRigCameras() {
             var camLeft = <TargetCamera>this._rigCameras[0];
@@ -425,6 +462,10 @@
             Vector3.TransformCoordinatesToRef(this.position, this._rigCamTransformMatrix, result);
         }
 
+        /**
+         * Gets the current object class name.
+         * @return the class name
+         */
         public getClassName(): string {
             return "TargetCamera";
         }

src/Cameras/babylon.touchCamera.ts

@@ -3,9 +3,16 @@ module BABYLON {
         return () => new TouchCamera(name, Vector3.Zero(), scene);
     });
 
-    // We're mainly based on the logic defined into the FreeCamera code
+    /**
+     * This represents a FPS type of camera controlled by touch.
+     * This is like a universal camera minus the Gamepad controls.
+     * @see http://doc.babylonjs.com/features/cameras#universal-camera
+     */
     export class TouchCamera extends FreeCamera {
-        //-- Begin properties for backward compatibility for inputs
+        /**
+         * Defines the touch sensibility for rotation.
+         * The higher the faster.
+         */
         public get touchAngularSensibility(): number {
             var touch = <FreeCameraTouchInput>this.inputs.attached["touch"];
             if (touch)
@@ -20,6 +27,10 @@ module BABYLON {
                 touch.touchAngularSensibility = value;
         }
 
+        /**
+         * Defines the touch sensibility for move.
+         * The higher the faster.
+         */
         public get touchMoveSensibility(): number {
             var touch = <FreeCameraTouchInput>this.inputs.attached["touch"];
             if (touch)
@@ -33,8 +44,16 @@ module BABYLON {
             if (touch)
                 touch.touchMoveSensibility = value;
         }
-        //-- end properties for backward compatibility for inputs
-
+        
+        /**
+         * Instantiates a new touch camera.
+         * This represents a FPS type of camera controlled by touch.
+         * This is like a universal camera minus the Gamepad controls.
+         * @see http://doc.babylonjs.com/features/cameras#universal-camera
+         * @param name Define the name of the camera in the scene
+         * @param position Define the start position of the camera in the scene
+         * @param scene Define the scene the camera belongs to
+         */
         constructor(name: string, position: Vector3, scene: Scene) {
             super(name, position, scene);
             this.inputs.addTouch();
@@ -42,6 +61,10 @@ module BABYLON {
             this._setupInputs();
         }
 
+        /**
+         * Gets the current object class name.
+         * @return the class name
+         */
         public getClassName(): string {
             return "TouchCamera";
         }

src/Cameras/babylon.universalCamera.ts

@@ -1,7 +1,14 @@
 module BABYLON {
-    // We're mainly based on the logic defined into the FreeCamera code
+    /**
+     * The Universal Camera is the one to choose for first person shooter type games, and works with all the keyboard, mouse, touch and gamepads. This replaces the earlier Free Camera, 
+     * which still works and will still be found in many Playgrounds.
+     * @see http://doc.babylonjs.com/features/cameras#universal-camera
+     */
     export class UniversalCamera extends TouchCamera {
-        //-- Begin properties for backward compatibility for inputs
+        /**
+         * Defines the gamepad rotation sensiblity.
+         * This is the threshold from when rotation starts to be accounted for to prevent jittering.
+         */
         public get gamepadAngularSensibility(): number {
             var gamepad = <FreeCameraGamepadInput>this.inputs.attached["gamepad"];
             if (gamepad)
@@ -16,6 +23,10 @@ module BABYLON {
                 gamepad.gamepadAngularSensibility = value;
         }
 
+        /**
+         * Defines the gamepad move sensiblity.
+         * This is the threshold from when moving starts to be accounted for for to prevent jittering.
+         */
         public get gamepadMoveSensibility(): number {
             var gamepad = <FreeCameraGamepadInput>this.inputs.attached["gamepad"];
             if (gamepad)
@@ -29,13 +40,24 @@ module BABYLON {
             if (gamepad)
                 gamepad.gamepadMoveSensibility = value;
         }
-        //-- end properties for backward compatibility for inputs
 
+        /**
+         * The Universal Camera is the one to choose for first person shooter type games, and works with all the keyboard, mouse, touch and gamepads. This replaces the earlier Free Camera, 
+         * which still works and will still be found in many Playgrounds.
+         * @see http://doc.babylonjs.com/features/cameras#universal-camera
+         * @param name Define the name of the camera in the scene
+         * @param position Define the start position of the camera in the scene
+         * @param scene Define the scene the camera belongs to
+         */
         constructor(name: string, position: Vector3, scene: Scene) {
             super(name, position, scene);
             this.inputs.addGamepad();
         }
 
+        /**
+         * Gets the current object class name.
+         * @return the class name
+         */
         public getClassName(): string {
             return "UniversalCamera";
         }

src/Cameras/babylon.virtualJoysticksCamera.ts

@@ -3,14 +3,32 @@
         return () => new VirtualJoysticksCamera(name, Vector3.Zero(), scene);
     });
 
-    // We're mainly based on the logic defined into the FreeCamera code
+    /**
+     * This represents a free type of camera. It can be usefull in First Person Shooter game for instance.
+     * It is identical to the Free Camera and simply adds by default a virtual joystick.
+     * Virtual Joysticks are on-screen 2D graphics that are used to control the camera or other scene items.
+     * @see http://doc.babylonjs.com/features/cameras#virtual-joysticks-camera
+     */
     export class VirtualJoysticksCamera extends FreeCamera {
         
+        /**
+         * Intantiates a VirtualJoysticksCamera. It can be usefull in First Person Shooter game for instance.
+         * It is identical to the Free Camera and simply adds by default a virtual joystick.
+         * Virtual Joysticks are on-screen 2D graphics that are used to control the camera or other scene items.
+         * @see http://doc.babylonjs.com/features/cameras#virtual-joysticks-camera
+         * @param name Define the name of the camera in the scene
+         * @param position Define the start position of the camera in the scene
+         * @param scene Define the scene the camera belongs to
+         */
         constructor(name: string, position: Vector3, scene: Scene) {
             super(name, position, scene);
             this.inputs.addVirtualJoystick();
         }
 
+        /**
+         * Gets the current object class name.
+         * @return the class name
+         */
         public getClassName(): string {
             return "VirtualJoysticksCamera";
         }

src/Cameras/babylon.webvr.ts

@@ -46,25 +46,34 @@ interface VRDisplay extends EventTarget {
     /**
      * Passing the value returned by `requestAnimationFrame` to
      * `cancelAnimationFrame` will unregister the callback.
+     * @param handle Define the hanle of the request to cancel
      */
     cancelAnimationFrame(handle: number): void;
 
     /**
      * Stops presenting to the VRDisplay.
+     * @returns a promise to know when it stopped
      */
     exitPresent(): Promise<void>;
 
-    /* Return the current VREyeParameters for the given eye. */
+    /**
+     * Return the current VREyeParameters for the given eye.
+     * @param whichEye Define the eye we want the parameter for
+     * @returns the eye parameters
+     */
     getEyeParameters(whichEye: string): VREyeParameters;
 
     /**
      * Populates the passed VRFrameData with the information required to render
      * the current frame.
+     * @param frameData Define the data structure to populate
+     * @returns true if ok otherwise false
      */
     getFrameData(frameData: VRFrameData): boolean;
 
     /**
      * Get the layers currently being presented.
+     * @returns the list of VR layers
      */
     getLayers(): VRLayer[];
 
@@ -75,12 +84,14 @@ interface VRDisplay extends EventTarget {
      *
      * The VRPose will contain the position, orientation, velocity,
      * and acceleration of each of these properties.
+     * @returns the pose object
      */
     getPose(): VRPose;
 
     /**
      * Return the current instantaneous pose of the VRDisplay, with no
      * prediction applied.
+     * @returns the current instantaneous pose
      */
     getImmediatePose(): VRPose;
 
@@ -92,12 +103,16 @@ interface VRDisplay extends EventTarget {
      * identically to how window.requestAnimationFrame acts. Content should
      * make no assumptions of frame rate or vsync behavior as the HMD runs
      * asynchronously from other displays and at differing refresh rates.
+     * @param callback Define the eaction to run next frame
+     * @returns the request handle it
      */
     requestAnimationFrame(callback: FrameRequestCallback): number;
 
     /**
      * Begin presenting to the VRDisplay. Must be called in response to a user gesture.
      * Repeat calls while already presenting will update the VRLayers being displayed.
+     * @param layers Define the list of layer to present
+     * @returns a promise to know when the request has been fulfilled
      */
     requestPresent(layers: VRLayer[]): Promise<void>;
 
@@ -115,6 +130,7 @@ interface VRDisplay extends EventTarget {
      * in the HMD. Calling this function has the same effect on the source
      * canvas as any other operation that uses its source image, and canvases
      * created without preserveDrawingBuffer set to true will be cleared.
+     * @param pose Define the pose to submit
      */
     submitFrame(pose?: VRPose): void;
 }