[Cleanup] Files.app: Adds missing JSdoc annotations in file_manager/*.js.

chrome/browser/resources/file_manager/js/file_transfer_controller.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.
 
 /**
  * Global (placed in the window object) variable name to hold internal
  * file dragging information. Needed to show visual feedback while dragging
  * since DataTransfer object is in protected state. Reachable from other
  * file manager instances.
  */
@@ skipping 28 matching lines @@
    * @type {Array.<File>}
    * @private
    */
   this.selectedFileObjects_ = [];
 }
 
 FileTransferController.prototype = {
   __proto__: cr.EventTarget.prototype,
 
   /**
+   * @this {FileTransferController}

[mtomasz, 2013/02/14 04:38:56]

Shall we convert it to FileTransferController.prototype.attachDragSource etc to
be more consistent? (different cl of course)?

[yoshiki, 2013/02/14 06:17:36]

Yes, you're right and I'll convert them to
FileTransferController.prototype.attachDragSource after the refactoring period
in another CL.

On 2013/02/14 04:38:56, mtomasz wrote:

    * @param {cr.ui.List} list Items in the list will be draggable.
    */
   attachDragSource: function(list) {
     list.style.webkitUserDrag = 'element';
     list.addEventListener('dragstart', this.onDragStart_.bind(this, list));
     list.addEventListener('dragend', this.onDragEnd_.bind(this, list));
   },
 
   /**
+   * @this {FileTransferController}
    * @param {cr.ui.List} list List itself and its directory items will could
    *                          be drop target.
    * @param {boolean=} opt_onlyIntoDirectories If true only directory list
    *     items could be drop targets. Otherwise any other place of the list
    *     accetps files (putting it into the current directory).
    */
   attachDropTarget: function(list, opt_onlyIntoDirectories) {
     list.addEventListener('dragover', this.onDragOver_.bind(this,
                           !!opt_onlyIntoDirectories, list));
     list.addEventListener('dragenter', this.onDragEnterList_.bind(this, list));
     list.addEventListener('dragleave', this.onDragLeave_.bind(this, list));
     list.addEventListener('drop', this.onDrop_.bind(this,
                           !!opt_onlyIntoDirectories));
   },
 
+  /**

[mtomasz, 2013/02/14 04:38:56]

Description missing in several methods, but this maybe other cl?

[yoshiki, 2013/02/14 06:17:36]

There are a lot of missing description of method and variables, so I can't do in
this CL. We should add them when we modify around them.

On 2013/02/14 04:38:56, mtomasz wrote:

[mtomasz, 2013/02/14 07:40:09]

Sgtm!

+   * @this {FileTransferController}
+   */
   attachBreadcrumbsDropTarget: function(breadcrumbsController) {
     var container = breadcrumbsController.getContainer();
     container.addEventListener('dragover',
         this.onDragOver_.bind(this, true, null));
     container.addEventListener('dragenter',
         this.onDragEnterBreadcrumbs_.bind(this, breadcrumbsController));
     container.addEventListener('dragleave',
         this.onDragLeave_.bind(this, null));
     container.addEventListener('drop', this.onDrop_.bind(this, true));
   },
 
   /**
    * Attach handlers of copy, cut and paste operations to the document.
+   * @this {FileTransferController}
    */
   attachCopyPasteHandlers: function() {
     this.document_.addEventListener('beforecopy',
                                     this.onBeforeCopy_.bind(this));
     this.document_.addEventListener('copy',
                                     this.onCopy_.bind(this));
     this.document_.addEventListener('beforecut',
                                     this.onBeforeCut_.bind(this));
     this.document_.addEventListener('cut',
                                     this.onCut_.bind(this));
     this.document_.addEventListener('beforepaste',
                                     this.onBeforePaste_.bind(this));
     this.document_.addEventListener('paste',
                                     this.onPaste_.bind(this));
     this.copyCommand_ = this.document_.querySelector('command#copy');
   },
 
   /**
    * Write the current selection to system clipboard.
    *
+   * @this {FileTransferController}
    * @param {DataTransfer} dataTransfer DataTransfer from the event.
    * @param {string} effectAllowed Value must be valid for the
    *     |dataTransfer.effectAllowed| property ('move', 'copy', 'copyMove').
    */
   cutOrCopy_: function(dataTransfer, effectAllowed) {
     var directories = [];
     var files = [];
     var entries = this.selectedEntries_;
     for (var i = 0; i < entries.length; i++) {
       (entries[i].isDirectory ? directories : files).push(entries[i].fullPath);
     }
 
     // Tag to check it's filemanager data.
     dataTransfer.setData('fs/tag', 'filemanager-data');
 
     dataTransfer.setData('fs/isOnDrive', this.isOnDrive);
     if (this.currentDirectory)
       dataTransfer.setData('fs/sourceDir', this.currentDirectory.fullPath);
     dataTransfer.setData('fs/directories', directories.join('\n'));
     dataTransfer.setData('fs/files', files.join('\n'));
     dataTransfer.effectAllowed = effectAllowed;
     dataTransfer.setData('fs/effectallowed', effectAllowed);
 
     for (var i = 0; i < this.selectedFileObjects_.length; i++) {
       dataTransfer.items.add(this.selectedFileObjects_[i]);
     }
   },
 
   /**
    * Extracts source root from the |dataTransfer| object.

[mtomasz, 2013/02/14 04:38:56]

Shall we add an empty line between description and jsdoc fields?

[yoshiki, 2013/02/14 06:17:36]

I think we don't always need a blank line. But it is good to add it if it
provides better readability.

+   * @this {FileTransferController}
    * @param {DataTransfer} dataTransfer DataTransfer object from the event.
    * @return {string} Path or empty string (if unknown).
    */
   getSourceRoot_: function(dataTransfer) {
     var sourceDir = dataTransfer.getData('fs/sourceDir');
     if (sourceDir)
       return PathUtil.getRootPath(sourceDir);
 
     // For drive search, sourceDir will be set to null, so we should double
     // check that we are not on drive.
@@ skipping 10 matching lines @@
       if (views[i][DRAG_AND_DROP_GLOBAL_DATA])
         return views[i][DRAG_AND_DROP_GLOBAL_DATA].sourceRoot;
     }
 
     // Unknown source.
     return '';
   },
 
   /**
    * Queue up a file copy operation based on the current system clipboard.
+   * @this {FileTransferController}
    * @param {DataTransfer} dataTransfer System data transfer object.
    * @param {string=} opt_destinationPath Paste destination.
    * @param {string=} opt_effect Desired drop/paste effect. Could be
    *     'move'|'copy' (default is copy). Ignored if conflicts with
    *     |dataTransfer.effectAllowed|.
    * @return {string} Either "copy" or "move".
    */
   paste: function(dataTransfer, opt_destinationPath, opt_effect) {
     var destinationPath = opt_destinationPath ||
                           this.directoryModel_.getCurrentDirPath();
@@ skipping 21 matching lines @@
                               targetOnDrive);
     } else {
       console.log('Ignore move into the same folder');
     }
 
     return toMove ? 'move' : 'copy';
   },
 
   /**
    * Preloads an image thumbnail for the specified file entry.
+   * @this {FileTransferController}
    * @param {Entry} entry Entry to preload a thumbnail for.
    */
   preloadThumbnailImage_: function(entry) {
     var imageUrl = entry.toURL();
     var metadataTypes = 'thumbnail|filesystem';
     this.preloadedThumbnailImageNode_ = this.document_.createElement('div');
     this.preloadedThumbnailImageNode_.className = 'img-container';
     this.directoryModel_.getMetadataCache().get(
         imageUrl,
         metadataTypes,
         function(metadata) {
           new ThumbnailLoader(imageUrl,
                               ThumbnailLoader.LoaderType.IMAGE,
                               metadata).
               load(this.preloadedThumbnailImageNode_,
                    ThumbnailLoader.FillMode.FILL);
         }.bind(this));
   },
 
   /**
    * Renders a drag-and-drop thumbnail.
+   * @this {FileTransferController}
    * @return {HTMLElement} Element containing the thumbnail.
    */
   renderThumbnail_: function() {
     var length = this.selectedEntries_.length;
 
     var container = this.document_.querySelector('#drag-container');
     var contents = this.document_.createElement('div');
     contents.className = 'drag-contents';
     container.appendChild(contents);
 
@@ skipping 24 matching lines @@
     icon.className = 'detail-icon';
     icon.setAttribute('file-type-icon', FileType.getIcon(entry));
     contents.appendChild(icon);
     var label = this.document_.createElement('div');
     label.className = 'label';
     label.textContent = entry.name;
     contents.appendChild(label);
     return container;
   },
 
+  /**
+   * @this {FileTransferController}
+   */
   onDragStart_: function(list, event) {
     // Nothing selected.
     if (!this.selectedEntries_.length) {
       event.preventDefault();
       return;
     }
 
     var dt = event.dataTransfer;
     var dragThumbnail = this.renderThumbnail_();
     dt.setDragImage(dragThumbnail, 1000, 1000);
 
     if (this.canCopyOrDrag_(dt)) {
       if (this.canCutOrDrag_(dt))
         this.cutOrCopy_(dt, 'copyMove');
       else
         this.cutOrCopy_(dt, 'copy');
     } else {
       event.preventDefault();
     }
 
     window[DRAG_AND_DROP_GLOBAL_DATA] = {
       sourceRoot: this.directoryModel_.getCurrentRootPath()
     };
   },
 
+  /**
+   * @this {FileTransferController}
+   */
   onDragEnd_: function(list, event) {
     var container = this.document_.querySelector('#drag-container');
     container.textContent = '';
     this.setDropTarget_(null);
     this.setScrollSpeed_(null, 0);
     delete window[DRAG_AND_DROP_GLOBAL_DATA];
   },
 
+  /**
+   * @this {FileTransferController}
+   */
   onDragOver_: function(onlyIntoDirectories, list, event) {
     if (list) {
       // Scroll the list if mouse close to the top or the bottom.
       var rect = list.getBoundingClientRect();
       if (event.clientY - rect.top < rect.bottom - event.clientY) {
         this.setScrollSpeed_(list,
             -this.calculateScrollSpeed_(event.clientY - rect.top));
       } else {
         this.setScrollSpeed_(list,
             this.calculateScrollSpeed_(rect.bottom - event.clientY));
       }
     }
     event.preventDefault();
     var path = this.destinationPath_ ||
         (!onlyIntoDirectories && this.directoryModel_.getCurrentDirPath());
     event.dataTransfer.dropEffect = this.selectDropEffect_(event, path);
     event.preventDefault();
   },
 
+  /**
+   * @this {FileTransferController}
+   */
   onDragEnterList_: function(list, event) {
     event.preventDefault();  // Required to prevent the cursor flicker.
     this.lastEnteredTarget_ = event.target;
     var item = list.getListItemAncestor(event.target);
     item = item && list.isItem(item) ? item : null;
     if (item == this.dropTarget_)
       return;
 
     var entry = item && list.dataModel.item(item.listIndex);
     if (entry) {
       this.setDropTarget_(item, entry.isDirectory, event.dataTransfer,
           entry.fullPath);
     } else {
       this.setDropTarget_(null);
     }
   },
 
+  /**
+   * @this {FileTransferController}
+   */
   onDragEnterBreadcrumbs_: function(breadcrumbsContainer, event) {
     event.preventDefault();  // Required to prevent the cursor flicker.
     this.lastEnteredTarget_ = event.target;
     var path = breadcrumbsContainer.getTargetPath(event);
     if (!path)
       return;
 
     this.setDropTarget_(event.target, true, event.dataTransfer, path);
   },
 
+  /**
+   * @this {FileTransferController}
+   */
   onDragLeave_: function(list, event) {
     // If mouse moves from one element to another the 'dragenter'
     // event for the new element comes before the 'dragleave' event for
     // the old one. In this case event.target != this.lastEnteredTarget_
     // and handler of the 'dragenter' event has already caried of
     // drop target. So event.target == this.lastEnteredTarget_
     // could only be if mouse goes out of listened element.
     if (event.target == this.lastEnteredTarget_) {
       this.setDropTarget_(null);
       this.lastEnteredTarget_ = null;
     }
     if (event.target == list)
       this.setScrollSpeed_(list, 0);
   },
 
+  /**
+   * @this {FileTransferController}
+   */
   onDrop_: function(onlyIntoDirectories, event) {
     if (onlyIntoDirectories && !this.dropTarget_)
       return;
     var destinationPath = this.destinationPath_ ||
                           this.directoryModel_.getCurrentDirPath();
     if (!this.canPasteOrDrop_(event.dataTransfer, destinationPath))
       return;
     event.preventDefault();
     this.paste(event.dataTransfer, destinationPath,
                this.selectDropEffect_(event, destinationPath));
     this.setDropTarget_(null);
     this.setScrollSpeed_(null, 0);
   },
 
+  /**
+   * @this {FileTransferController}
+   */
   setDropTarget_: function(domElement, isDirectory, opt_dataTransfer,
                            opt_destinationPath) {
     if (this.dropTarget_ == domElement)
       return;
 
     /** @type {string?} */
     this.destinationPath_ = null;
     if (domElement) {
       if (isDirectory &&
           this.canPasteOrDrop_(opt_dataTransfer, opt_destinationPath)) {
@@ skipping 14 matching lines @@
       clearTimeout(this.navigateTimer_);
       this.navigateTimer_ = undefined;
     }
     if (domElement && isDirectory && opt_destinationPath) {
       this.navigateTimer_ = setTimeout(function() {
         this.directoryModel_.changeDirectory(opt_destinationPath);
       }.bind(this), 2000);
     }
   },
 
-  isDocumentWideEvent_: function(event) {
+  /**
+   * @this {FileTransferController}
+   * @return {boolean} Returns false if {@code <input type="text">} element is
+   *     currently active. Otherwise, returns true.
+   */
+  isDocumentWideEvent_: function() {
     return this.document_.activeElement.nodeName.toLowerCase() != 'input' ||
         this.document_.activeElement.type.toLowerCase() != 'text';
   },
 
+  /**
+   * @this {FileTransferController}
+   */
   onCopy_: function(event) {
-    if (!this.isDocumentWideEvent_(event) ||
+    if (!this.isDocumentWideEvent_() ||
         !this.canCopyOrDrag_()) {
       return;
     }
     event.preventDefault();
     this.cutOrCopy_(event.clipboardData, 'copy');
     this.notify_('selection-copied');
   },
 
+  /**
+   * @this {FileTransferController}
+   */
   onBeforeCopy_: function(event) {
-    if (!this.isDocumentWideEvent_(event))
+    if (!this.isDocumentWideEvent_())
       return;
 
     // queryCommandEnabled returns true if event.returnValue is false.
     event.returnValue = !this.canCopyOrDrag_();
   },
 
+  /**
+   * @this {FileTransferController}
+   * @return {boolean} Returns true if some files are selected and all the file
+   *     on drive is available to be copied. Otherwise, returns false.
+   */
   canCopyOrDrag_: function() {
     if (this.isOnDrive &&
         this.directoryModel_.isDriveOffline() &&
         !this.allDriveFilesAvailable)
       return false;
     return this.selectedEntries_.length > 0;
   },
 
+  /**
+   * @this {FileTransferController}
+   */
   onCut_: function(event) {
-    if (!this.isDocumentWideEvent_(event) ||
+    if (!this.isDocumentWideEvent_() ||
         !this.canCutOrDrag_()) {
       return;
     }
     event.preventDefault();
     this.cutOrCopy_(event.clipboardData, 'move');
     this.notify_('selection-cut');
   },
 
+  /**
+   * @this {FileTransferController}
+   */
   onBeforeCut_: function(event) {
-    if (!this.isDocumentWideEvent_(event))
+    if (!this.isDocumentWideEvent_())
       return;
     // queryCommandEnabled returns true if event.returnValue is false.
     event.returnValue = !this.canCutOrDrag_();
   },
 
+  /**
+   * @this {FileTransferController}
+   * @return {boolean}  Returns true if some files are selected and all the file
+   *     on drive is available to be cut. Otherwise, returns false.
+   */
   canCutOrDrag_: function() {
     return !this.readonly && this.canCopyOrDrag_();
   },
 
+  /**
+   * @this {FileTransferController}
+   */
   onPaste_: function(event) {
     // Need to update here since 'beforepaste' doesn't fire.
-    if (!this.isDocumentWideEvent_(event) ||
+    if (!this.isDocumentWideEvent_() ||
         !this.canPasteOrDrop_(event.clipboardData)) {
       return;
     }
     event.preventDefault();
     var effect = this.paste(event.clipboardData);
 
     // On cut, we clear the clipboard after the file is pasted/moved so we don't
     // try to move/delete the original file again.
     if (effect == 'move') {
       this.simulateCommand_('cut', function(event) {
         event.preventDefault();
         event.clipboardData.setData('fs/clear', '');
       });
     }
   },
 
+  /**
+   * @this {FileTransferController}
+   */
   onBeforePaste_: function(event) {
-    if (!this.isDocumentWideEvent_(event))
+    if (!this.isDocumentWideEvent_())
       return;
     // queryCommandEnabled returns true if event.returnValue is false.
     event.returnValue = !this.canPasteOrDrop_(event.clipboardData);
   },
 
+  /**
+   * @this {FileTransferController}
+   * @return {boolean}  Returns true if {@code opt_destinationPath} is
+   *     available to be pasted to. Otherwise, returns false.
+   */
   canPasteOrDrop_: function(dataTransfer, opt_destinationPath) {
     var destinationPath = opt_destinationPath ||
                           this.directoryModel_.getCurrentDirPath();
     if (this.directoryModel_.isPathReadOnly(destinationPath)) {
       return false;
     }
     if (this.directoryModel_.isSearching())
       return false;
 
     if (!dataTransfer.types || dataTransfer.types.indexOf('fs/tag') == -1)
       return false;  // Unsupported type of content.
     if (dataTransfer.getData('fs/tag') == '') {
       // Data protected. Other checks are not possible but it makes sense to
       // let the user try.
       return true;
     }
 
     var directories = dataTransfer.getData('fs/directories').split('\n').
                       filter(function(d) { return d != ''; });
 
     for (var i = 0; i < directories.length; i++) {
       if (destinationPath.substr(0, directories[i].length) == directories[i])
         return false;  // recursive paste.
     }
 
     return true;
   },
 
+  /**
+   * Execute paste command.
+   *
+   * @this {FileTransferController}
+   * @return {boolean}  Returns true, the paste is success. Otherwise, returns
+   *     false.
+   */
   queryPasteCommandEnabled: function() {
     if (!this.isDocumentWideEvent_()) {
       return false;
     }
 
     // HACK(serya): return this.document_.queryCommandEnabled('paste')
     // should be used.
     var result;
     this.simulateCommand_('paste', function(event) {
       result = this.canPasteOrDrop_(event.clipboardData);
     }.bind(this));
     return result;
   },
 
   /**
    * Allows to simulate commands to get access to clipboard.
+   * @this {FileTransferController}
    * @param {string} command 'copy', 'cut' or 'paste'.
    * @param {Function} handler Event handler.
    */
   simulateCommand_: function(command, handler) {
     var iframe = this.document_.querySelector('#command-dispatcher');
     var doc = iframe.contentDocument;
     doc.addEventListener(command, handler);
     doc.execCommand(command);
     doc.removeEventListener(command, handler);
   },
 
+  /**
+   * @this {FileTransferController}
+   */
   onSelectionChanged_: function(event) {
     var entries = this.selectedEntries_;
     var files = this.selectedFileObjects_ = [];
     this.preloadedThumbnailImageNode_ = null;
 
     var fileEntries = [];
     for (var i = 0; i < entries.length; i++) {
       if (entries[i].isFile)
         fileEntries.push(entries[i]);
     }
@@ skipping 30 matching lines @@
         this.copyCommand_.disabled = !this.canCopyOrDrag_();
 
         if (this.allDriveFilesAvailable)
           prepareFileObjects();
       }.bind(this));
     } else {
       prepareFileObjects();
     }
   },
 
+  /**
+   * @this {FileTransferController}
+   */
   get currentDirectory() {
     if (this.directoryModel_.isSearching() && this.isOnDrive)
       return null;
     return this.directoryModel_.getCurrentDirEntry();
   },
 
+  /**
+   * @this {FileTransferController}
+   */
   get readonly() {
     return this.directoryModel_.isReadOnly();
   },
 
+  /**
+   * @this {FileTransferController}
+   */
   get isOnDrive() {
     return this.directoryModel_.getCurrentRootType() === RootType.DRIVE;
   },
 
+  /**
+   * @this {FileTransferController}
+   */
   notify_: function(eventName) {
     var self = this;
     // Set timeout to avoid recursive events.
     setTimeout(function() {
       cr.dispatchSimpleEvent(self, eventName);
     }, 0);
   },
 
   /**
+   * @this {FileTransferController}
    * @type {Array.<Entry>}
    */
   get selectedEntries_() {
     var list = this.directoryModel_.getFileList();
     var selectedIndexes = this.directoryModel_.getFileListSelection().
                                selectedIndexes;
     var entries = selectedIndexes.map(function(index) {
       return list.item(index);
     });
 
     // TODO(serya): Diagnostics for http://crbug/129642
     if (entries.indexOf(undefined) != -1) {
       var index = entries.indexOf(undefined);
       entries = entries.filter(function(e) { return !!e; });
       console.error('Invalid selection found: list items: ', list.length,
                     'wrong indexe value: ', selectedIndexes[index],
                     'Stack trace: ', new Error().stack);
     }
     return entries;
   },
 
+  /**
+   * @this {FileTransferController}
+   * @return {string}  Returns the appropriate drop query type ('none', 'move'
+   *     or copy') to the current modifiers status and the destination.
+   */
   selectDropEffect_: function(event, destinationPath) {
     if (!destinationPath ||
         this.directoryModel_.isPathReadOnly(destinationPath))
       return 'none';
     if (event.dataTransfer.effectAllowed == 'copyMove' &&
         this.getSourceRoot_(event.dataTransfer) ==
             PathUtil.getRootPath(destinationPath) &&
         !event.ctrlKey) {
       return 'move';
     }
     if (event.dataTransfer.effectAllowed == 'copyMove' &&
         event.shiftKey) {
       return 'move';
     }
     return 'copy';
   },
 
+  /**
+   * @this {FileTransferController}
+   * @return {number} Returns an appropriate scroll speed to the distance.
+   */
   calculateScrollSpeed_: function(distance) {
     var SCROLL_AREA = 25;  // Pixels.
     var MIN_SCROLL_SPEED = 50; // Pixels/sec.
     var MAX_SCROLL_SPEED = 300;  // Pixels/sec.
     if (distance < 0 || distance > SCROLL_AREA)
       return 0;
     return MAX_SCROLL_SPEED - (MAX_SCROLL_SPEED - MIN_SCROLL_SPEED) *
         (distance / SCROLL_AREA);
   },
 
+  /**
+   * @this {FileTransferController}
+   */
   setScrollSpeed_: function(list, speed) {
     var SCROLL_INTERVAL = 200;   // Milliseconds.
     if (speed == 0 && this.scrollInterval_) {
       clearInterval(this.scrollInterval_);
       this.scrollInterval_ = null;
     } else if (speed != 0 && !this.scrollInterval_) {
       this.scrollInterval_ = setInterval(this.scroll_.bind(this),
                                          SCROLL_INTERVAL);
     }
     this.scrollStep_ = speed * SCROLL_INTERVAL / 1000;
     this.scrollList_ = list;
   },
 
+  /**
+   * @this {FileTransferController}
+   */
   scroll_: function() {
     if (this.scrollList_)
       this.scrollList_.scrollTop += this.scrollStep_;
   }
 };