Merge pull request #5181 from kcoley/documentGamepadFiles

Document gamepad files

dist/preview release/typedocValidationBaseline.json

@@ -1576,255 +1576,6 @@
         }
       }
     },
-    "Gamepad": {
-      "Class": {
-        "Comments": {
-          "MissingText": true
-        }
-      },
-      "Constructor": {
-        "new Gamepad": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "id": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "index": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "browserGamepad": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "leftStickX": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "leftStickY": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "rightStickX": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "rightStickY": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        }
-      },
-      "Property": {
-        "browserGamepad": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "id": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "index": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "isConnected": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "leftStick": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "rightStick": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "type": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "GAMEPAD": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "GENERIC": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "POSE_ENABLED": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "XBOX": {
-          "Comments": {
-            "MissingText": true
-          }
-        }
-      },
-      "Method": {
-        "dispose": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "onleftstickchanged": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "callback": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "onrightstickchanged": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "callback": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "update": {
-          "Comments": {
-            "MissingText": true
-          }
-        }
-      }
-    },
-    "GamepadManager": {
-      "Class": {
-        "Comments": {
-          "MissingText": true
-        }
-      },
-      "Constructor": {
-        "new GamepadManager": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "_scene": {
-              "Comments": {
-                "MissingText": true
-              },
-              "Naming": {
-                "NotCamelCase": true
-              }
-            }
-          }
-        }
-      },
-      "Property": {
-        "gamepads": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "onGamepadConnectedObservable": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "onGamepadDisconnectedObservable": {
-          "Comments": {
-            "MissingText": true
-          }
-        }
-      },
-      "Method": {
-        "dispose": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "getGamepadByType": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "type": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        }
-      }
-    },
-    "GenericPad": {
-      "Class": {
-        "Comments": {
-          "MissingText": true
-        }
-      },
-      "Property": {
-        "onButtonDownObservable": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "onButtonUpObservable": {
-          "Comments": {
-            "MissingText": true
-          }
-        }
-      },
-      "Method": {
-        "onbuttondown": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "callback": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "onbuttonup": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "callback": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        }
-      }
-    },
     "GroundMesh": {
       "Class": {
         "Comments": {
@@ -8186,44 +7937,6 @@
         }
       }
     },
-    "StickValues": {
-      "Class": {
-        "Comments": {
-          "MissingText": true
-        }
-      },
-      "Constructor": {
-        "new StickValues": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "x": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "y": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        }
-      },
-      "Property": {
-        "x": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "y": {
-          "Comments": {
-            "MissingText": true
-          }
-        }
-      }
-    },
     "StringDictionary": {
       "Property": {
         "count": {

src/Gamepad/babylon.gamepad.ts

@@ -1,18 +1,56 @@
 module BABYLON {
+    /**
+     * Represents a gamepad control stick position
+     */
     export class StickValues {
-        constructor(public x: number, public y: number) {
+        /**
+         * Initializes the gamepad x and y control stick values
+         * @param x The x component of the gamepad control stick value
+         * @param y The y component of the gamepad control stick value
+         */
+        constructor(
+            /**
+             * The x component of the control stick
+             */
+            public x: number, 
+            /**
+             * The y component of the control stick
+             */
+            public y: number
+        ) {
         }
     }
 
+    /**
+     * An interface which manages callbacks for gamepad button changes
+     */
     export interface GamepadButtonChanges {
+        /**
+         * Called when a gamepad has been changed
+         */
         changed: boolean;
+        /**
+         * Called when a gamepad press event has been triggered
+         */
         pressChanged: boolean;
+        /**
+         * Called when a touch event has been triggered
+         */
         touchChanged: boolean;
+        /**
+         * Called when a value has changed
+         */
         valueChanged: boolean;
     }
 
+    /**
+     * Represents a gamepad
+     */
     export class Gamepad {
 
+        /**
+         * Specifies what type of gamepad this represents
+         */
         public type: number;
 
         private _leftStick: StickValues = { x: 0, y: 0 };
@@ -26,21 +64,69 @@
         private _rightStickAxisX: number;
         private _rightStickAxisY: number;
 
+        /**
+         * Triggered when the left control stick has been changed
+         */
         private _onleftstickchanged: (values: StickValues) => void;
+
+        /**
+         * Triggered when the right control stick has been changed
+         */
         private _onrightstickchanged: (values: StickValues) => void;
 
+        /**
+         * Represents a gamepad controller
+         */
         public static GAMEPAD = 0;
+        /**
+         * Represents a generic controller
+         */
         public static GENERIC = 1;
+        /**
+         * Represents an XBox controller
+         */
         public static XBOX = 2;
+        /**
+         * Represents a pose-enabled controller
+         */
         public static POSE_ENABLED = 3;
 
+        /**
+         * Specifies whether the left control stick should be Y-inverted
+         */
         protected _invertLeftStickY: boolean = false;
 
+        /**
+         * Specifies if the gamepad has been connected
+         */
         public get isConnected(): boolean {
             return this._isConnected;
         }
 
-        constructor(public id: string, public index: number, public browserGamepad: any, leftStickX: number = 0, leftStickY: number = 1, rightStickX: number = 2, rightStickY: number = 3) {
+        /**
+         * Initializes the gamepad
+         * @param id The id of the gamepad
+         * @param index The index of the gamepad
+         * @param browserGamepad The browser gamepad
+         * @param leftStickX The x component of the left joystick
+         * @param leftStickY The y component of the left joystick
+         * @param rightStickX The x component of the right joystick
+         * @param rightStickY The y component of the right joystick
+         */
+        constructor(
+            /**
+             * The id of the gamepad
+             */
+            public id: string, 
+            /**
+             * The index of the gamepad
+             */
+            public index: number, 
+            /**
+             * The browser gamepad
+             */
+            public browserGamepad: any, 
+            leftStickX: number = 0, leftStickY: number = 1, rightStickX: number = 2, rightStickY: number = 3) {
             this.type = Gamepad.GAMEPAD;
             this._leftStickAxisX = leftStickX;
             this._leftStickAxisY = leftStickY;
@@ -54,26 +140,46 @@
             }
         }
 
+        /**
+         * Callback triggered when the left joystick has changed
+         * @param callback 
+         */
         public onleftstickchanged(callback: (values: StickValues) => void) {
             this._onleftstickchanged = callback;
         }
 
+        /**
+         * Callback triggered when the right joystick has changed
+         * @param callback 
+         */
         public onrightstickchanged(callback: (values: StickValues) => void) {
             this._onrightstickchanged = callback;
         }
 
+        /**
+         * Gets the left joystick
+         */
         public get leftStick(): StickValues {
             return this._leftStick;
         }
+        /**
+         * Sets the left joystick values
+         */
         public set leftStick(newValues: StickValues) {
             if (this._onleftstickchanged && (this._leftStick.x !== newValues.x || this._leftStick.y !== newValues.y)) {
                 this._onleftstickchanged(newValues);
             }
             this._leftStick = newValues;
         }
+        /**
+         * Gets the right joystick
+         */
         public get rightStick(): StickValues {
             return this._rightStick;
         }
+        /**
+         * Sets the right joystick value
+         */
         public set rightStick(newValues: StickValues) {
             if (this._onrightstickchanged && (this._rightStick.x !== newValues.x || this._rightStick.y !== newValues.y)) {
                 this._onrightstickchanged(newValues);
@@ -81,6 +187,10 @@
             this._rightStick = newValues;
         }
 
+        /**
+         * Updates the gamepad joystick positions
+         */
+
         public update() {
             if (this._leftStick) {
                 this.leftStick = { x: this.browserGamepad.axes[this._leftStickAxisX], y: this.browserGamepad.axes[this._leftStickAxisY] };
@@ -93,25 +203,51 @@
             }
         }
 
+        /**
+         * Disposes the gamepad
+         */
         public dispose() {
         }
     }
 
+    /**
+     * Represents a generic gamepad
+     */
     export class GenericPad extends Gamepad {
         private _buttons: Array<number>;
         private _onbuttondown: (buttonPressed: number) => void;
         private _onbuttonup: (buttonReleased: number) => void;
 
+        /**
+         * Observable triggered when a button has been pressed
+         */
         public onButtonDownObservable = new Observable<number>();
+        /**
+         * Observable triggered when a button has been released
+         */
         public onButtonUpObservable = new Observable<number>();
 
+        /**
+         * Callback triggered when a button has been pressed
+         * @param callback Called when a button has been pressed
+         */
         public onbuttondown(callback: (buttonPressed: number) => void) {
             this._onbuttondown = callback;
         }
+        /**
+         * Callback triggered when a button has been released
+         * @param callback Called when a button has been released
+         */
         public onbuttonup(callback: (buttonReleased: number) => void) {
             this._onbuttonup = callback;
         }
 
+        /**
+         * Initializes the generic gamepad
+         * @param id The id of the generic gamepad
+         * @param index The index of the generic gamepad
+         * @param browserGamepad The browser gamepad
+         */
         constructor(id: string, index: number, browserGamepad: any) {
             super(id, index, browserGamepad);
             this.type = Gamepad.GENERIC;
@@ -138,6 +274,9 @@
             return newValue;
         }
 
+        /**
+         * Updates the generic gamepad
+         */
         public update() {
             super.update();
             for (var index = 0; index < this._buttons.length; index++) {
@@ -145,6 +284,9 @@
             }
         }
 
+        /**
+         * Disposes the generic gamepad
+         */
         public dispose() {
             super.dispose();
             this.onButtonDownObservable.clear();

src/Gamepad/babylon.gamepadManager.ts

@@ -1,4 +1,7 @@
 module BABYLON {
+    /**
+     * Manager for handling gamepads
+     */
     export class GamepadManager {
         private _babylonGamepads: Array<Gamepad> = [];
         private _oneGamepadConnected: boolean = false;
@@ -8,12 +11,23 @@
         private _gamepadEventSupported: boolean;
         private _gamepadSupport: () => Array<any>;
 
+        /**
+         * observable to be triggered when the gamepad controller has been connected
+         */
         public onGamepadConnectedObservable: Observable<Gamepad>;
+
+        /**
+         * observable to be triggered when the gamepad controller has been disconnected
+         */
         public onGamepadDisconnectedObservable = new Observable<Gamepad>();
 
         private _onGamepadConnectedEvent: Nullable<(evt: any) => void>;
         private _onGamepadDisconnectedEvent: Nullable<(evt: any) => void>;
 
+        /**
+         * Initializes the gamepad manager
+         * @param _scene BabylonJS scene
+         */
         constructor(private _scene?: Scene) {
             if (!Tools.IsWindowObjectExist()) {
                 this._gamepadEventSupported = false;
@@ -87,10 +101,18 @@
             }
         }
 
+        /**
+         * The gamepads in the game pad manager
+         */
         public get gamepads(): Gamepad[] {
             return this._babylonGamepads;
         }
 
+        /**
+         * Get the gamepad controllers based on type
+         * @param type The type of gamepad controller
+         * @returns Nullable gamepad
+         */
         public getGamepadByType(type: number = Gamepad.XBOX): Nullable<Gamepad> {
             for (var gamepad of this._babylonGamepads) {
                 if (gamepad && gamepad.type === type) {
@@ -101,6 +123,9 @@
             return null;
         }
 
+        /**
+         * Disposes the gamepad manager
+         */
         public dispose() {
             if (this._gamepadEventSupported) {
                 if (this._onGamepadConnectedEvent) {

src/Gamepad/babylon.gamepadSceneComponent.ts

@@ -27,15 +27,24 @@ module BABYLON {
         configurable: true
     });
 
+    /**
+     * Interface representing a free camera inputs manager
+     */
     export interface FreeCameraInputsManager {
         addGamepad(): FreeCameraInputsManager;
     }
     
+    /**
+     * Adds a gamepad to the free camera inputs manager
+     */
     FreeCameraInputsManager.prototype.addGamepad = function(): FreeCameraInputsManager {
         this.add(new FreeCameraGamepadInput());
         return this;
     }
 
+    /**
+     * Interface representing an arc rotate camera inputs manager
+     */
     export interface ArcRotateCameraInputsManager {
         /**
          * Adds gamepad input support to the ArcRotateCamera InputManager.
@@ -44,6 +53,9 @@ module BABYLON {
         addGamepad(): ArcRotateCameraInputsManager;
     }
     
+    /**
+     * Adds a gamepad to the arc rotate camera inputs manager
+     */
     ArcRotateCameraInputsManager.prototype.addGamepad = function(): ArcRotateCameraInputsManager {
         this.add(new ArcRotateCameraGamepadInput());
         return this;

src/Gamepad/babylon.xboxGamepad.ts

@@ -110,11 +110,14 @@
         }
  
         /**
-         * Gets or sets left trigger value
+         * Gets the left trigger value
          */
         public get leftTrigger(): number {
             return this._leftTrigger;
         }
+        /**
+         * Sets the left trigger value
+         */
         public set leftTrigger(newValue: number) {
             if (this._onlefttriggerchanged && this._leftTrigger !== newValue) {
                 this._onlefttriggerchanged(newValue);
@@ -123,11 +126,14 @@
         }
 
         /**
-         * Gets or sets right trigger value
+         * Gets the right trigger value
          */        
         public get rightTrigger(): number {
             return this._rightTrigger;
         }
+        /**
+         * Sets the right trigger value
+         */
         public set rightTrigger(newValue: number) {
             if (this._onrighttriggerchanged && this._rightTrigger !== newValue) {
                 this._onrighttriggerchanged(newValue);
@@ -208,114 +214,184 @@
             return newValue;
         }
 
-        /** Gets or sets value of A button */
+        /** 
+         * Gets the value of the `A` button 
+         */
         public get buttonA(): number {
             return this._buttonA;
         }
+        /**
+         * Sets the value of the `A` button
+         */
         public set buttonA(value) {
             this._buttonA = this._setButtonValue(value, this._buttonA, Xbox360Button.A);
         }
 
-        /** Gets or sets value of B button */
+        /** 
+         * Gets the value of the `B` button 
+         */
         public get buttonB(): number {
             return this._buttonB;
         }
+        /** 
+         * Sets the value of the `B` button 
+         */
         public set buttonB(value) {
             this._buttonB = this._setButtonValue(value, this._buttonB, Xbox360Button.B);
         }
 
-        /** Gets or sets value of X button */       
+        /** 
+         * Gets the value of the `X` button 
+         */      
         public get buttonX(): number {
             return this._buttonX;
         }
+        /** 
+         * Sets the value of the `X` button 
+         */
         public set buttonX(value) {
             this._buttonX = this._setButtonValue(value, this._buttonX, Xbox360Button.X);
         }
 
-        /** Gets or sets value of Y button */        
+        /** 
+         * Gets the value of the `Y` button 
+         */      
         public get buttonY(): number {
             return this._buttonY;
         }
+        /** 
+         * Sets the value of the `Y` button 
+         */
         public set buttonY(value) {
             this._buttonY = this._setButtonValue(value, this._buttonY, Xbox360Button.Y);
         }        
         
-        /** Gets or sets value of Start button  */
+        /** 
+         * Gets the value of the `Start` button 
+         */
         public get buttonStart(): number {
             return this._buttonStart;
         }
+        /** 
+         * Sets the value of the `Start` button 
+         */
         public set buttonStart(value) {
             this._buttonStart = this._setButtonValue(value, this._buttonStart, Xbox360Button.Start);
         }
 
-        /** Gets or sets value of Back button  */        
+        /** 
+         * Gets the value of the `Back` button 
+         */ 
         public get buttonBack(): number {
             return this._buttonBack;
         }
+        /** 
+         * Sets the value of the `Back` button 
+         */
         public set buttonBack(value) {
             this._buttonBack = this._setButtonValue(value, this._buttonBack, Xbox360Button.Back);
         }
 
-        /** Gets or sets value of Left button  */        
+        /** 
+         * Gets the value of the `Left` button 
+         */     
         public get buttonLB(): number {
             return this._buttonLB;
         }
+        /** 
+         * Sets the value of the `Left` button 
+         */
         public set buttonLB(value) {
             this._buttonLB = this._setButtonValue(value, this._buttonLB, Xbox360Button.LB);
         }
 
-        /** Gets or sets value of Right button  */        
+        /** 
+         * Gets the value of the `Right` button 
+         */     
         public get buttonRB(): number {
             return this._buttonRB;
         }
+        /** 
+         * Sets the value of the `Right` button 
+         */
         public set buttonRB(value) {
             this._buttonRB = this._setButtonValue(value, this._buttonRB, Xbox360Button.RB);
         }
 
-        /** Gets or sets value of left stick */  
+        /** 
+         * Gets the value of the Left joystick 
+         */ 
         public get buttonLeftStick(): number {
             return this._buttonLeftStick;
         }
+        /** 
+         * Sets the value of the Left joystick 
+         */ 
         public set buttonLeftStick(value) {
             this._buttonLeftStick = this._setButtonValue(value, this._buttonLeftStick, Xbox360Button.LeftStick);
         }
 
-        /** Gets or sets value of right stick */  
+        /** 
+         * Gets the value of the Right joystick 
+         */ 
         public get buttonRightStick(): number {
             return this._buttonRightStick;
         }
+        /** 
+         * Sets the value of the Right joystick 
+         */ 
         public set buttonRightStick(value) {
             this._buttonRightStick = this._setButtonValue(value, this._buttonRightStick, Xbox360Button.RightStick);
         }
 
-        /** Gets or sets value of DPad up */  
+        /** 
+         * Gets the value of D-pad up 
+         */  
         public get dPadUp(): number {
             return this._dPadUp;
         }
+        /** 
+         * Sets the value of D-pad up 
+         */
         public set dPadUp(value) {
             this._dPadUp = this._setDPadValue(value, this._dPadUp, Xbox360Dpad.Up);
         }
 
-        /** Gets or sets value of DPad down */  
+        /** 
+         * Gets the value of D-pad down 
+         */
         public get dPadDown(): number {
             return this._dPadDown;
         }
+        /** 
+         * Sets the value of D-pad down 
+         */
         public set dPadDown(value) {
             this._dPadDown = this._setDPadValue(value, this._dPadDown, Xbox360Dpad.Down);
         }
 
-        /** Gets or sets value of DPad left */  
+        /** 
+         * Gets the value of D-pad left 
+         */ 
         public get dPadLeft(): number {
             return this._dPadLeft;
         }
+        /** 
+         * Sets the value of D-pad left 
+         */
         public set dPadLeft(value) {
             this._dPadLeft = this._setDPadValue(value, this._dPadLeft, Xbox360Dpad.Left);
         }
 
-        /** Gets or sets value of DPad right */  
+        /** 
+         * Gets the value of D-pad right 
+         */
         public get dPadRight(): number {
             return this._dPadRight;
         }
+        /** 
+         * Sets the value of D-pad right 
+         */
         public set dPadRight(value) {
             this._dPadRight = this._setDPadValue(value, this._dPadRight, Xbox360Dpad.Right);
         }
@@ -362,6 +438,9 @@
             }
         }
 
+        /**
+         * Disposes the gamepad
+         */
         public dispose(){
             super.dispose();
             this.onButtonDownObservable.clear();