[Photo Editor] Javascript style fixes

chrome/browser/resources/file_manager/js/image_editor/image_view.js

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 /**
  * The overlay displaying the image.
+ * @param {HTMLElement} container The container element.
+ * @param {Viewport} viewport The viewport.
+ * @param {MetadataProvider} metadataProvider The metadataProvider.
  */
 function ImageView(container, viewport, metadataProvider) {
   this.container_ = container;
   this.viewport_ = viewport;
   this.document_ = container.ownerDocument;
   this.contentGeneration_ = 0;
   this.displayedContentGeneration_ = 0;
   this.displayedViewportGeneration_ = 0;
 
   this.imageLoader_ = new ImageUtil.ImageLoader(this.document_);
@@ skipping 19 matching lines @@
    */
   this.screenImage_ = null;
 
   this.localImageTransformFetcher_ = function(url, callback) {
     metadataProvider.fetchLocal(url, function(metadata) {
       callback(metadata.imageTransform);
     });
   };
 }
 
+/**
+ * Duration of image editing transitions.
+ */
 ImageView.ANIMATION_DURATION = 180;
+
+/**
+ * A timeout for use with setTimeout when one wants to wait until the animation
+ * is done. Times 2 is added as a safe margin.
+ */
 ImageView.ANIMATION_WAIT_INTERVAL = ImageView.ANIMATION_DURATION * 2;
+
+/**
+ * If the user flips though images faster than this interval we do not apply
+ * the slide-in/slide-out transition.
+ */
 ImageView.FAST_SCROLL_INTERVAL = 300;
 
+/**
+ * Image load type: full resolution image loaded from cache.
+ */
 ImageView.LOAD_TYPE_CACHED_FULL = 0;
+
+/**
+ * Image load type: screeb resolution preview loaded from cache.
+ */
 ImageView.LOAD_TYPE_CACHED_SCREEN = 1;
+
+/**
+ * Image load type: image read from file.
+ */
 ImageView.LOAD_TYPE_IMAGE_FILE = 2;
+
+/**
+ * Image load type: video loaded.
+ */
 ImageView.LOAD_TYPE_VIDEO_FILE = 3;
+
+/**
+ * Image load type: error occurred.
+ */
 ImageView.LOAD_TYPE_ERROR = 4;
+
+/**
+ * The total number of load types.
+ */
 ImageView.LOAD_TYPE_TOTAL = 5;
 
 ImageView.prototype = {__proto__: ImageBuffer.Overlay.prototype};
 
-// Draw below overlays with the default zIndex.
+/**
+ * Draw below overlays with the default zIndex.
+ * @return {number} Z-index
+ */
 ImageView.prototype.getZIndex = function() { return -1 };
 
+/**
+ * Draw the image on screen.
+ */
 ImageView.prototype.draw = function() {
   if (!this.contentCanvas_)  // Do nothing if the image content is not set.
     return;
 
   var forceRepaint = false;
 
   if (this.displayedViewportGeneration_ !=
       this.viewport_.getCacheGeneration()) {
     this.displayedViewportGeneration_ = this.viewport_.getCacheGeneration();
 
     this.setupDeviceBuffer(this.screenImage_);
 
     forceRepaint = true;
   }
 
   if (forceRepaint ||
       this.displayedContentGeneration_ != this.contentGeneration_) {
     this.displayedContentGeneration_ = this.contentGeneration_;
 
     ImageUtil.trace.resetTimer('paint');
     this.paintDeviceRect(this.viewport_.getDeviceClipped(),
         this.contentCanvas_, this.viewport_.getImageClipped());
     ImageUtil.trace.reportTimer('paint');
   }
 };
 
-ImageView.prototype.getCursorStyle = function (x, y, mouseDown) {
+/**
+ * @param {number} x X pointer position.
+ * @param {number} y Y pointer position.
+ * @param {boolean} mouseDown True if mouse is down.
+ * @return {string} CSS cursor style.
+ */
+ImageView.prototype.getCursorStyle = function(x, y, mouseDown) {
   // Indicate that the image is draggable.
   if (this.viewport_.isClipped() &&
       this.viewport_.getScreenClipped().inside(x, y))
     return 'move';
 
   return null;
 };
 
-ImageView.prototype.getDragHandler = function (x, y) {
+/**
+ * @param {number} x X pointer position.
+ * @param {number} y Y pointer position.
+ * @return {function} The closure to call on drag.
+ */
+ImageView.prototype.getDragHandler = function(x, y) {
   var cursor = this.getCursorStyle(x, y);
   if (cursor == 'move') {
     // Return the handler that drags the entire image.
     return this.viewport_.createOffsetSetter(x, y);
   }
 
   return null;
 };
 
+/**
+ * @return {number} The cache generation.
+ */
 ImageView.prototype.getCacheGeneration = function() {
   return this.contentGeneration_;
 };
 
+/**
+ * Invalidate the caches to force redrawing the screen canvas.
+ */
 ImageView.prototype.invalidateCaches = function() {
   this.contentGeneration_++;
 };
 
+/**
+ * @return {HTMLCanvasElement} The content canvas element.
+ */
 ImageView.prototype.getCanvas = function() { return this.contentCanvas_ };
 
+/**
+ * @return {boolean} True if the a valid image is currently loaded.
+ */
 ImageView.prototype.hasValidImage = function() {
   return !this.preview_ && this.contentCanvas_ && this.contentCanvas_.width;
 };
 
+/**
+ * @return {HTMLVideoElement} The video element.
+ */
 ImageView.prototype.getVideo = function() { return this.videoElement_ };
 
+/**
+ * @return {HTMLCanvasElement} The cached thumbnail image.
+ */
 ImageView.prototype.getThumbnail = function() { return this.thumbnailCanvas_ };
 
+/**
+ * @return {number} The content revision number.
+ */
 ImageView.prototype.getContentRevision = function() {
   return this.contentRevision_;
 };
 
 /**
  * Copy an image fragment from a full resolution canvas to a device resolution
  * canvas.
  *
  * @param {Rect} deviceRect Rectangle in the device coordinates.
  * @param {HTMLCanvasElement} canvas Full resolution canvas.
  * @param {Rect} imageRect Rectangle in the full resolution canvas.
  */
-ImageView.prototype.paintDeviceRect = function (deviceRect, canvas, imageRect) {
+ImageView.prototype.paintDeviceRect = function(deviceRect, canvas, imageRect) {
   // Map screen canvas (0,0) to (deviceBounds.left, deviceBounds.top)
   var deviceBounds = this.viewport_.getDeviceClipped();
   deviceRect = deviceRect.shift(-deviceBounds.left, -deviceBounds.top);
 
   // The source canvas may have different physical size than the image size
   // set at the viewport. Adjust imageRect accordingly.
   var bounds = this.viewport_.getImageBounds();
   var scaleX = canvas.width / bounds.width;
   var scaleY = canvas.height / bounds.height;
   imageRect = new Rect(imageRect.left * scaleX, imageRect.top * scaleY,
                        imageRect.width * scaleX, imageRect.height * scaleY);
   Rect.drawImage(
-      this.screenImage_.getContext("2d"), canvas, deviceRect, imageRect);
+      this.screenImage_.getContext('2d'), canvas, deviceRect, imageRect);
 };
 
 /**
  * Create an overlay canvas with properties similar to the screen canvas.
  * Useful for showing quick feedback when editing.
  *
  * @return {HTMLCanvasElement} Overlay canvas
  */
 ImageView.prototype.createOverlayCanvas = function() {
   var canvas = this.document_.createElement('canvas');
@@ skipping 20 matching lines @@
   canvas.style.left = deviceRect.left + 'px';
   canvas.style.top = deviceRect.top + 'px';
 
   // Scale the canvas down down to screen pixels.
   this.setTransform(canvas);
 };
 
 /**
  * @return {ImageData} A new ImageData object with a copy of the content.
  */
-ImageView.prototype.copyScreenImageData = function () {
-  return this.screenImage_.getContext("2d").getImageData(
+ImageView.prototype.copyScreenImageData = function() {
+  return this.screenImage_.getContext('2d').getImageData(
       0, 0, this.screenImage_.width, this.screenImage_.height);
 };
 
+/**
+ * @return {boolean} True if the image is currently being loaded.
+ */
 ImageView.prototype.isLoading = function() {
   return this.imageLoader_.isBusy();
 };
 
+/**
+ * Cancel the current image loading operation. The callbacks will be ignored.
+ */
 ImageView.prototype.cancelLoad = function() {
   this.imageLoader_.cancel();
 };
 
 /**
  * Load and display a new image.
  *
  * Loads the thumbnail first, then replaces it with the main image.
  * Takes into account the image orientation encoded in the metadata.
  *
- * @param {number} id Unique image id for caching purposes
- * @param {string|HTMLCanvasElement} source
- * @param {Object} metadata
+ * @param {number} id Unique image id for caching purposes.
+ * @param {string} url Image url.
+ * @param {Object} metadata Metadata.
  * @param {Object} slide Slide-in animation direction.
  * @param {function(number} opt_callback The parameter is the load type.
  */
 ImageView.prototype.load = function(
-    id, source, metadata, slide, opt_callback) {
+    id, url, metadata, slide, opt_callback) {
 
-  metadata = metadata|| {};
+  metadata = metadata || {};
 
   ImageUtil.metrics.startInterval(ImageUtil.getMetricName('DisplayTime'));
 
   var self = this;
 
   this.contentID_ = id;
   this.contentRevision_ = -1;
 
-  var loadingVideo = FileType.getMediaType(source) == 'video';
+  var loadingVideo = FileType.getMediaType(url) == 'video';
   if (loadingVideo) {
     var video = this.document_.createElement('video');
     if (metadata.thumbnailURL) {
       video.setAttribute('poster', metadata.thumbnailURL);
       this.replace(video, slide); // Show the poster immediately.
     }
     video.addEventListener('loadedmetadata', onVideoLoad);
     video.addEventListener('error', onVideoLoad);
 
     // Do not try no stream when offline.
-    video.src = (navigator.onLine && metadata.streamingURL) || source;
+    video.src = (navigator.onLine && metadata.streamingURL) || url;
     video.load();
 
     function onVideoLoad() {
       video.removeEventListener('loadedmetadata', onVideoLoad);
       video.removeEventListener('error', onVideoLoad);
       displayMainImage(ImageView.LOAD_TYPE_VIDEO_FILE, slide,
           !!metadata.thumbnailURL /* preview shown */, video);
     }
     return;
   }
-  var readyContent = this.getReadyContent(id, source);
-  if (readyContent) {
+  var cached = this.contentCache_.getItem(id);
+  if (cached) {
     displayMainImage(ImageView.LOAD_TYPE_CACHED_FULL, slide,
-        false /* no preview */, readyContent);
+        false /* no preview */, cached);
   } else {
     var cachedScreen = this.screenCache_.getItem(id);
     if (cachedScreen) {
       // We have a cached screen-scale canvas, use it instead of a thumbnail.
       displayThumbnail(ImageView.LOAD_TYPE_CACHED_SCREEN, slide, cachedScreen);
       // As far as the user can tell the image is loaded. We still need to load
       // the full res image to make editing possible, but we can report now.
       ImageUtil.metrics.recordInterval(ImageUtil.getMetricName('DisplayTime'));
     } else if (metadata.thumbnailURL) {
       this.imageLoader_.load(
           metadata.thumbnailURL,
           function(url, callback) { callback(metadata.thumbnailTransform); },
           displayThumbnail.bind(null, ImageView.LOAD_TYPE_IMAGE_FILE, slide));
     } else {
-      loadMainImage(ImageView.LOAD_TYPE_IMAGE_FILE, slide, source,
+      loadMainImage(ImageView.LOAD_TYPE_IMAGE_FILE, slide, url,
           false /* no preview*/, 0 /* delay */);
     }
   }
 
   function displayThumbnail(loadType, slide, canvas) {
     // The thumbnail may have different aspect ratio than the main image.
     // Force the main image proportions to avoid flicker.
     var time = Date.now();
 
     var mainImageLoadDelay = ImageView.ANIMATION_WAIT_INTERVAL;
     var mainImageSlide = slide;
 
     // Do not do slide-in animation when scrolling very fast.
     if (self.lastLoadTime_ &&
         (time - self.lastLoadTime_) < ImageView.FAST_SCROLL_INTERVAL) {
       mainImageSlide = 0;
     }
     self.lastLoadTime_ = time;
 
     if (canvas.width) {
       if (metadata.remote) {
         // We do not know the main image size, but chances are that it is large
         // enough. Show the thumbnail at the maximum possible scale.
         var bounds = self.viewport_.getScreenBounds();
-        var scale = Math.min (bounds.width / canvas.width,
-                              bounds.height / canvas.height);
+        var scale = Math.min(bounds.width / canvas.width,
+                             bounds.height / canvas.height);
         self.replace(canvas, slide,
             canvas.width * scale, canvas.height * scale, true /* preview */);
       } else {
         self.replace(canvas, slide,
             metadata.width, metadata.height, true /* preview */);
       }
       if (!mainImageSlide) mainImageLoadDelay = 0;
       mainImageSlide = 0;
     } else {
       // Thumbnail image load failed, loading the main image immediately.
       mainImageLoadDelay = 0;
     }
-    loadMainImage(loadType, mainImageSlide, source,
+    loadMainImage(loadType, mainImageSlide, url,
         canvas.width != 0, mainImageLoadDelay);
   }
 
   function loadMainImage(loadType, slide, contentURL, previewShown, delay) {
     if (self.prefetchLoader_.isLoading(contentURL)) {
       // The image we need is already being prefetched. Initiating another load
       // would be a waste. Hijack the load instead by overriding the callback.
       self.prefetchLoader_.setCallback(
           displayMainImage.bind(null, loadType, slide, previewShown));
 
@@ skipping 33 matching lines @@
         loadType != ImageView.LOAD_TYPE_CACHED_SCREEN) {
       ImageUtil.metrics.recordInterval(ImageUtil.getMetricName('DisplayTime'));
     }
     ImageUtil.metrics.recordEnum(ImageUtil.getMetricName('LoadMode'),
         loadType, ImageView.LOAD_TYPE_TOTAL);
     if (opt_callback) opt_callback(loadType);
   }
 };
 
 /**
- * Try to get the canvas from the content cache or from the source.
- *
- * @param {number} id Unique image id for caching purposes
- * @param {string|HTMLCanvasElement} source
- */
-ImageView.prototype.getReadyContent = function(id, source) {
-  if (source.constructor.name == 'HTMLCanvasElement')
-    return source;
-
-  return this.contentCache_.getItem(id);
-};
-
-/**
  * Prefetch an image.
  *
- * @param {number} id Unique image id for caching purposes
- * @param {string|HTMLCanvasElement} source
+ * @param {number} id Unique image id for caching purposes.
+ * @param {string} url The image url.
  */
-ImageView.prototype.prefetch = function(id, source) {
+ImageView.prototype.prefetch = function(id, url) {
   var self = this;
   function prefetchDone(canvas) {
     if (canvas.width)
       self.contentCache_.putItem(id, canvas);
   }
 
-  var cached = this.getReadyContent(id, source);
+  var cached = this.contentCache_.getItem(id);
   if (cached) {
     prefetchDone(cached);
-  } else if (FileType.getMediaType(source) == 'image') {
+  } else if (FileType.getMediaType(url) == 'image') {
     // Evict the LRU item before we allocate the new canvas to avoid unneeded
     // strain on memory.
     this.contentCache_.evictLRU();
 
     this.prefetchLoader_.load(
-        source,
+        url,
         this.localImageTransformFetcher_,
         prefetchDone,
         ImageView.ANIMATION_WAIT_INTERVAL);
   }
 };
 
+/**
+ *
+ * @param {HTMLCanvasElement|HTMLVideoElement} content The image element.
+ * @param {boolean} opt_reuseScreenCanvas True if it is OK to reuse the screen
+ *   resolution canvas.
+ * @param {number} opt_width Image width.
+ * @param {number} opt_height Image height.
+ * @param {boolean} opt_preview True if the image is a preview (not full res).
+ * @private
+ */
 ImageView.prototype.replaceContent_ = function(
     content, opt_reuseScreenCanvas, opt_width, opt_height, opt_preview) {
 
   if (content.constructor.name == 'HTMLVideoElement') {
     this.contentCanvas_ = null;
     this.videoElement_ = content;
     this.screenImage_ = content;
     this.screenImage_.className = 'image';
     return;
   }
@@ skipping 26 matching lines @@
 
     // TODO(kaznacheev): It is better to pass screenImage_ as it is usually
     // much smaller than contentCanvas_ and still contains the entire image.
     // Once we implement zoom/pan we should pass contentCanvas_ instead.
     this.updateThumbnail_(this.screenImage_);
 
     this.contentRevision_++;
     for (var i = 0; i != this.contentCallbacks_.length; i++) {
       try {
         this.contentCallbacks_[i]();
-      } catch(e) {
+      } catch (e) {
         console.error(e);
       }
     }
   }
 };
 
+/**
+ * Add a listener for content changes.
+ * @param {function} callback Callback.
+ */
 ImageView.prototype.addContentCallback = function(callback) {
   this.contentCallbacks_.push(callback);
 };
 
+/**
+ * Update the cached thumbnail image.
+ *
+ * @param {HTMLCanvasElement} canvas The source canvas.
+ * @private
+ */
 ImageView.prototype.updateThumbnail_ = function(canvas) {
   ImageUtil.trace.resetTimer('thumb');
   var pixelCount = 10000;
   var downScale =
       Math.max(1, Math.sqrt(canvas.width * canvas.height / pixelCount));
 
   this.thumbnailCanvas_ = canvas.ownerDocument.createElement('canvas');
   this.thumbnailCanvas_.width = Math.round(canvas.width / downScale);
   this.thumbnailCanvas_.height = Math.round(canvas.height / downScale);
   Rect.drawImage(this.thumbnailCanvas_.getContext('2d'), canvas);
   ImageUtil.trace.reportTimer('thumb');
 };
 
 /**
  * Replace the displayed image, possibly with slide-in animation.
  *
- * @param {HTMLCanvasElement|HTMLVideoElement} content
+ * @param {HTMLCanvasElement|HTMLVideoElement} content The image element.
  * @param {number} opt_slide Slide-in animation direction.
  *           <0 for right-to-left, > 0 for left-to-right, 0 for no animation.
+ * @param {number} opt_width Image width.
+ * @param {number} opt_height Image height.
+ * @param {boolean} opt_preview True if the image is a preview (not full res).
  */
 ImageView.prototype.replace = function(
     content, opt_slide, opt_width, opt_height, opt_preview) {
   var oldScreenImage = this.screenImage_;
 
   this.replaceContent_(content, !opt_slide, opt_width, opt_height, opt_preview);
 
   opt_slide = opt_slide || 0;
   // TODO(kaznacheev): The line below is too obscure.
   // Refactor the whole 'slide' thing for clarity.
@@ skipping 138 matching lines @@
       0);
 
   setTimeout(function() { newScreenImage.removeAttribute('fade') }, 0);
 
   setTimeout(function() {
     oldScreenImage.parentNode.removeChild(oldScreenImage);
   }, ImageView.ANIMATION_WAIT_INTERVAL);
 };
 
 
+/**
+ * Generic cache with a limited capacity and LRU eviction.
+ *
+ * @param {number} capacity Maximum number of cached item.
+ */
 ImageView.Cache = function(capacity) {
   this.capacity_ = capacity;
   this.map_ = {};
   this.order_ = [];
 };
 
+/**
+ * Fetch the item from the cache.
+ *
+ * @param {string} id The item ID.
+ * @return {object} The cached item.
+ */
 ImageView.Cache.prototype.getItem = function(id) { return this.map_[id] };
 
+/**
+ * Put the item into the cache.
+ * @param {string} id The item ID.
+ * @param {object} item The item object.
+ * @param {boolean} opt_keepLRU True if the LRU order should not be modified.
+ */
 ImageView.Cache.prototype.putItem = function(id, item, opt_keepLRU) {
   var pos = this.order_.indexOf(id);
 
   if ((pos >= 0) != (id in this.map_))
     throw new Error('Inconsistent cache state');
 
   if (id in this.map_) {
     if (!opt_keepLRU) {
       // Move to the end (most recently used).
       this.order_.splice(pos, 1);
       this.order_.push(id);
     }
   } else {
     this.evictLRU();
     this.order_.push(id);
   }
 
   this.map_[id] = item;
 
   if (this.order_.length > this.capacity_)
     throw new Error('Exceeded cache capacity');
 };
 
+/**
+ * Evict the least recently used items.
+ */
 ImageView.Cache.prototype.evictLRU = function() {
   if (this.order_.length == this.capacity_) {
     var id = this.order_.shift();
     delete this.map_[id];
   }
 };