Lot of doc

js/l3d/src/canvases/MousePointer.js

@@ -1,19 +1,89 @@
+/**
+ * Contains a canvas to place over the renderer for FPS-style pointer
+ * It's based on a javascript 2d-canvas : you'll need to render it manually.
+ *
+ * @example
+ * var container = documeng.getElementById('container');
+ * var renderer = new THREE.WebGLRenderer();
+ * renderer.setSize(width, height);
+ *
+ * var pointerCamera = new L3D.PointerCamera(50, width/height, near, fat, renderer, container);
+ * var mousePointer = new L3D.MousePointer(pointerCamera);
+ * mousePointer.domElement.width = width;
+ * mousePointer.domElement.height = height;
+ *
+ * container.appendChild(mousePointer.domElement);
+ * container.appendChild(renderer.domElement);
+ *
+ * mousePointer.render(L3D.MousePointer.BLACK);
+ * @memberof L3D
+ * @constructor
+ */
 L3D.MousePointer = function(camera) {
 
+    /**
+     * @type {elemnt}
+     * @description The document element to add on top of the renderer
+     */
     this.domElement = document.createElement('canvas');
+
     this.domElement.style.position = 'absolute';
     this.domElement.style.cssFloat = 'top-left';
+
+    /**
+     * @type {CanvasRenderingContext2D}
+     * @description The context of the canvas
+     */
     this.ctx = this.domElement.getContext('2d');
+
+    /**
+     * @type {Number}
+     * @description The size of the gun sight
+     */
     this.size = 10;
-    this.drawn = false;
+
     camera.mousePointer = this;
+
+    /**
+     * @type {Number}
+     * @description a L3D.MousePointer style. The current style of the mouse pointer
+     */
     this.style = L3D.MousePointer.NONE;
+
 };
 
+/**
+ * @memberof L3D.MousePointer
+ * @type {Number}
+ * @static
+ * @description Empty style : the canvas is fully transparent
+ */
 L3D.MousePointer.NONE = 0;
+
+/**
+ * @memberof L3D.MousePointer
+ * @type {Number}
+ * @static
+ * @description Black style : the canvas contains only a white cross in the middle of the screen
+ */
 L3D.MousePointer.BLACK = 1;
+
+/**
+ * @memberof L3D.MousePointer
+ * @type {Number}
+ * @static
+ * @description Red style : the canvas contains only a white and red cross in the midlle
+ * (used for hovering stuff)
+ */
 L3D.MousePointer.RED = 2;
 
+/**
+ * @memberof L3D.MousePointer
+ * @static
+ * @description Converts a style to a color
+ * @param {Number} style a L3D.MousePointer style (NONE, BLACK, or RED)
+ * @returns {string} null if input is NONE, a hex color string else
+ */
 L3D.MousePointer.toColor = function(style) {
 
     switch (style) {
@@ -29,9 +99,28 @@ L3D.MousePointer.toColor = function(style) {
 
 };
 
-L3D.MousePointer.prototype.render = function(style) {
+/**
+ * Re-renders the canvas
+ * For performance reasons, the rendering is done only if the style changed.
+ * @param {Number} style the L3D.MousePointer style you want to render
+ * @param {Boolean} force force the re-rendering (even if the style did not change)
+ *
+ */
+L3D.MousePointer.prototype.render = function(style, force) {
 
-    if (this.style !== style) {
+    if (style === undefined) {
+
+        style = L3D.MousePointer.NONE;
+
+    }
+
+    if (force === undefined) {
+
+        force = false;
+
+    }
+
+    if (this.style !== style || force) {
 
         if (style === L3D.MousePointer.NONE) {
 
@@ -75,8 +164,18 @@ L3D.MousePointer.prototype.render = function(style) {
 
 };
 
-L3D.MousePointer.prototype.clear = function() {
+/**
+ * Clears the canvas
+ * @param {Boolean} force force the clearing (even if the style did not change)
+ */
+L3D.MousePointer.prototype.clear = function(force) {
 
-    this.render(L3D.MousePointer.NONE);
+    if (force === undefined) {
+
+        force = false;
+
+    }
+
+    this.render(L3D.MousePointer.NONE, force);
 
 };

js/l3d/src/canvases/Previewer.js

@@ -2,16 +2,72 @@ Math.clamp = Math.clamp || function(number, min, max) {
     return Math.max(Math.min(number, max), min);
 };
 
+/**
+ * @memberof L3D
+ * @constructor
+ * @param {THREE.Renderer} renderer the renderer to use
+ * @param {THREE.Scene} scene the scene to render
+ * @description Displays a small preview of a camera
+ */
 L3D.Previewer = function(renderer, scene) {
+    /**
+     * @type {element}
+     * @description The document element to add on top of the renderer
+     */
     this.domElement = document.createElement('canvas');
+
+    /**
+     * @type {CanvasRenderingContext2D}
+     * @description The context of domElement
+     */
     this.ctx = this.domElement.getContext('2d');
+
+    /**
+     * @type {THREE.Renderer}
+     * @description The renderer to use
+     */
     this.renderer = renderer;
-    this.fixed = false;
+
+    /**
+     * @type {THREE.Scene}
+     * @description The scene to render
+     */
     this.scene = scene;
+
+    /**
+     * @type {Boolean}
+     * @description true if the preview should be stuck at the bottom left of the container,
+     * false if it should appear near the mouse
+     */
+    this.fixed = false;
+
+    /**
+     * @private
+     * @type {Boolean}
+     * @description true if the rendering as already been done
+     */
     this.drawn = false;
+
+    /**
+     * @private
+     * @type {Boolean}
+     * @description true if the rendering was done before
+     */
     this.drawnBefore = false;
 };
 
+/**
+ * Renders the preview
+ * @param {Object} pref an object containing :
+ * <ul>
+ *  <li><code>go</code> : a boolean if the rendering should be done</li>
+ *  <li><code>x</code> : the x coordinate of the mouse</li>
+ *  <li><code>y</code> : the y coordinate of the mouse</li>
+ *  <li><code>camera</code> : the camera to use for the preview</li>
+ * </ul>
+ * @param {Number} container_width width of the container
+ * @param {Number} container_height height of the container
+ */
 L3D.Previewer.prototype.render = function(prev, container_width, container_height) {
     var width, height, left, bottom;
 
@@ -79,6 +135,9 @@ L3D.Previewer.prototype.render = function(prev, container_width, container_heigh
 
 };
 
+/**
+ * Clears the borders of the preview
+ */
 L3D.Previewer.prototype.clear = function() {
     if (this.clearNeeded) {
         this.domElement.width = this.domElement.width;
@@ -86,10 +145,19 @@ L3D.Previewer.prototype.clear = function() {
     }
 };
 
+/**
+ * Setter for the fixed preview
+ * @param {Boolean} true if you want to fix the preview, false otherwise
+ */
 L3D.Previewer.prototype.fixedRecommendation = function(bool) {
     this.fixed = bool;
 };
 
+/**
+ * @private
+ * @description Update flags
+ * @param {Boolean} arg if the update drew something
+ */
 L3D.Previewer.prototype.update = function(arg) {
     this.drawnBefore = this.drawn;
     this.drawn = arg;

js/l3d/src/canvases/StartCanvas.js

@@ -1,15 +1,37 @@
+/**
+ * @memberof L3D
+ * @constructor
+ * @description Displays a translucid canvas over the renderer to enable interaction to lock pointer
+ */
 L3D.StartCanvas = function(camera) {
 
+    /**
+     * @type {elemnt}
+     * @description The document element to add on top of the renderer
+     */
     this.domElement = document.createElement('canvas');
     this.domElement.style.position = 'absolute';
     this.domElement.style.cssFloat = 'top-left';
+
+    /**
+     * @type {CanvasRenderingContext2D}
+     * @description The context of the canvas
+     */
     this.ctx = this.domElement.getContext('2d');
+
+    /**
+     * @type {Boolean}
+     * @description true if the canvas is displayed
+     */
     this.shown = false;
 
     camera.startCanvas = this;
 
 };
 
+/**
+ * Shows the canvas with a string in the middle of it
+ */
 L3D.StartCanvas.prototype.render = function() {
 
     if (!this.shown) {
@@ -30,6 +52,9 @@ L3D.StartCanvas.prototype.render = function() {
 
 };
 
+/**
+ * Hide canvas
+ */
 L3D.StartCanvas.prototype.clear = function() {
 
     if (this.shown) {