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

chrome/browser/resources/file_manager/js/file_copy_manager.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.
 
 if (chrome.extension) {
   var getContentWindows = function() {
     return chrome.extension.getViews();
   };
 }
 
 /**
+ * @param {DirectoryEntry} root Root directory entry.
  * @constructor
- * @param {DirectoryEntry} root Root directory entry.
  */
 function FileCopyManager(root) {
   this.copyTasks_ = [];
   this.deleteTasks_ = [];
   this.lastDeleteId_ = 0;
   this.cancelObservers_ = [];
   this.cancelRequested_ = false;
   this.cancelCallback_ = null;
   this.root_ = root;
   this.unloadTimeout_ = null;
 
   window.addEventListener('error', function(e) {
     this.log_('Unhandled error: ', e.message, e.filename + ':' + e.lineno);
   }.bind(this));
 }
 
 var fileCopyManagerInstance = null;
 
 /**
  * Get FileCopyManager instance. In case is hasn't been initialized, a new
  * instance is created.
+ *
  * @param {DirectoryEntry} root Root entry.
  * @return {FileCopyManager} A FileCopyManager instance.
  */
 FileCopyManager.getInstance = function(root) {
   if (fileCopyManagerInstance === null) {
     fileCopyManagerInstance = new FileCopyManager(root);
   }
   return fileCopyManagerInstance;
 };
 
 /**
  * A record of a queued copy operation.
  *
  * Multiple copy operations may be queued at any given time.  Additional
  * Tasks may be added while the queue is being serviced.  Though a
  * cancel operation cancels everything in the queue.
  *
  * @param {DirectoryEntry} sourceDirEntry Source directory.
  * @param {DirectoryEntry} targetDirEntry Target directory.
+ * @constructor
  */
 FileCopyManager.Task = function(sourceDirEntry, targetDirEntry) {
   this.sourceDirEntry = sourceDirEntry;
   this.targetDirEntry = targetDirEntry;
   this.originalEntries = null;
 
   this.pendingDirectories = [];
   this.pendingFiles = [];
   this.pendingBytes = 0;
 
@@ skipping 115 matching lines @@
     var rename = this.renamedDirectories_[index];
     if (path.indexOf(rename.from) == 0) {
       path = rename.to + path.substr(rename.from.length);
     }
   }
   return path;
 };
 
 /**
  * Error class used to report problems with a copy operation.
- * @constructor
+ *
  * @param {string} reason Error type.
  * @param {Object} data Additional data.
+ * @constructor
  */
 FileCopyManager.Error = function(reason, data) {
   this.reason = reason;
   this.code = FileCopyManager.Error[reason];
   this.data = data;
 };
 
 /** @const */
 FileCopyManager.Error.CANCELLED = 0;
 /** @const */
@@ skipping 78 matching lines @@
 
   rv.percentage = rv.completedBytes / rv.totalBytes;
   if (rv.pendingItems === 1)
     rv.filename = pendingFile.name;
 
   return rv;
 };
 
 /**
  * Send an event to all the FileManager windows.
+ *
  * @private
  * @param {string} eventName Event name.
  * @param {Object} eventArgs An object with arbitrary event parameters.
  */
 FileCopyManager.prototype.sendEvent_ = function(eventName, eventArgs) {
   if (this.cancelRequested_)
     return;  // Swallow events until cancellation complete.
 
   eventArgs.status = this.getStatus();
 
   var windows = getContentWindows();
   for (var i = 0; i < windows.length; i++) {
     var w = windows[i];
     if (w.fileCopyManagerWrapper)
       w.fileCopyManagerWrapper.onEvent(eventName, eventArgs);
   }
 };
 
 /**
  * Unloads the host page in 5 secs of idleing. Need to be called
  * each time this.copyTasks_.length or this.deleteTasks_.length
  * changed.
+ *
  * @private
  */
 FileCopyManager.prototype.maybeScheduleCloseBackgroundPage_ = function() {
   if (this.copyTasks_.length === 0 && this.deleteTasks_.length === 0) {
     if (this.unloadTimeout_ === null)
       this.unloadTimeout_ = setTimeout(close, 5000);
   } else if (this.unloadTimeout_) {
     clearTimeout(this.unloadTimeout_);
     this.unloadTimeout_ = null;
   }
 };
 
 /**
  * Write to console.log on all the active FileManager windows.
+ *
  * @private
  */
 FileCopyManager.prototype.log_ = function() {
   var windows = getContentWindows();
   for (var i = 0; i < windows.length; i++) {
     windows[i].console.log.apply(windows[i].console, arguments);
   }
 };
 
 /**
  * Dispatch a simple copy-progress event with reason and optional err data.
+ *
  * @private
  * @param {string} reason Event type.
  * @param {FileCopyManager.Error} opt_err Error.
  */
 FileCopyManager.prototype.sendProgressEvent_ = function(reason, opt_err) {
   var event = {};
   event.reason = reason;
   if (opt_err)
     event.error = opt_err;
   this.sendEvent_('copy-progress', event);
 };
 
 /**
  * Dispatch an event of file operation completion (allows to update the UI).
+ *
  * @private

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

Sorry, missed this. Should @private be the last one? I've seen it in most places
as the last one.

[yoshiki, 2013/02/14 08:46:11]

Ok, let's put '@private' after '@param' in the future.

On 2013/02/14 07:40:10, mtomasz wrote:

  * @param {string} reason Completed file operation: 'movied|copied|deleted'.
  * @param {Array.<Entry>} affectedEntries deleted ot created entries.
  */
 FileCopyManager.prototype.sendOperationEvent_ = function(reason,
                                                          affectedEntries) {
   var event = {};
   event.reason = reason;
   event.affectedEntries = affectedEntries;
   this.sendEvent_('copy-operation-complete', event);
 };
 
 /**
  * Completely clear out the copy queue, either because we encountered an error
  * or completed successfully.
+ *
  * @private
  */
 FileCopyManager.prototype.resetQueue_ = function() {
   for (var i = 0; i < this.cancelObservers_.length; i++)
     this.cancelObservers_[i]();
 
   this.copyTasks_ = [];
   this.cancelObservers_ = [];
   this.maybeScheduleCloseBackgroundPage_();
 };
 
 /**
  * Request that the current copy queue be abandoned.
+ *
  * @param {Function} opt_callback On cancel.
  */
 FileCopyManager.prototype.requestCancel = function(opt_callback) {
   this.cancelRequested_ = true;
   if (this.cancelCallback_)
     this.cancelCallback_();
   if (opt_callback)
     this.cancelObservers_.push(opt_callback);
 
   // If there is any active task it will eventually call maybeCancel_.
   // Otherwise call it right now.
   if (this.copyTasks_.length == 0)
     this.doCancel_();
 };
 
 /**
  * Perform the bookkeeping required to cancel.
+ *
  * @private
  */
 FileCopyManager.prototype.doCancel_ = function() {
   this.resetQueue_();
   this.cancelRequested_ = false;
   this.sendProgressEvent_('CANCELLED');
 };
 
 /**
  * Used internally to check if a cancel has been requested, and handle
  * it if so.
+ *
  * @private
  * @return {boolean} If canceled.
  */
 FileCopyManager.prototype.maybeCancel_ = function() {
   if (!this.cancelRequested_)
     return false;
 
   this.doCancel_();
   return true;
 };
 
 /**
  * Convert string in clipboard to entries and kick off pasting.
+ *
  * @param {Object} clipboard Clipboard contents.
  * @param {string} targetPath Target path.
  * @param {boolean} targetOnDrive If target is on Drive.
  */
 FileCopyManager.prototype.paste = function(clipboard, targetPath,
                                            targetOnDrive) {
   var self = this;
   var results = {
     sourceDirEntry: null,
     entries: [],
@@ skipping 77 matching lines @@
  */
 FileCopyManager.prototype.isOnSameRoot = function(sourceEntry,
                                                   targetDirEntry,
                                                   targetOnDrive) {
   return PathUtil.getRootPath(sourceEntry.fullPath) ==
          PathUtil.getRootPath(targetDirEntry.fullPath);
 };
 
 /**
  * Initiate a file copy.
+ *
  * @param {DirectoryEntry} sourceDirEntry Source directory.
  * @param {DirectoryEntry} targetDirEntry Target directory.
  * @param {Array.<Entry>} entries Entries to copy.
  * @param {boolean} deleteAfterCopy In case of move.
  * @param {boolean} sourceOnDrive Source directory on Drive.
  * @param {boolean} targetOnDrive Target directory on Drive.
  * @return {FileCopyManager.Task} Copy task.
  */
 FileCopyManager.prototype.queueCopy = function(sourceDirEntry,
                                                targetDirEntry,
@@ skipping 27 matching lines @@
       self.sendProgressEvent_('PROGRESS');
     }
   });
 
   return copyTask;
 };
 
 /**
  * Service all pending tasks, as well as any that might appear during the
  * copy.
+ *
  * @private
  */
 FileCopyManager.prototype.serviceAllTasks_ = function() {
   var self = this;
 
   var onTaskError = function(err) {
     if (self.maybeCancel_())
       return;
     self.sendProgressEvent_('ERROR', err);
     self.resetQueue_();
@@ skipping 20 matching lines @@
 
   // If the queue size is 1 after pushing our task, it was empty before,
   // so we need to kick off queue processing and dispatch BEGIN event.
 
   this.sendProgressEvent_('BEGIN');
   this.serviceNextTask_(onTaskSuccess, onTaskError);
 };
 
 /**
  * Service all entries in the next copy task.
+ *
  * @private

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

Last?

  * @param {Function} successCallback On success.
  * @param {Function} errorCallback On error.
  */
 FileCopyManager.prototype.serviceNextTask_ = function(
     successCallback, errorCallback) {
   var self = this;
   var task = this.copyTasks_[0];
 
   var onFilesystemError = function(err) {
     errorCallback(new FileCopyManager.Error('FILESYSTEM_ERROR', err));
@@ skipping 514 matching lines @@
   sourceEntry.file(onSourceFileFound, errorCallback);
 };
 
 /**
  * Timeout before files are really deleted (to allow undo).
  */
 FileCopyManager.DELETE_TIMEOUT = 30 * 1000;
 
 /**
  * Schedules the files deletion.
+ *
  * @param {Array.<Entry>} entries The entries.
  * @param {function(number)} callback Callback gets the scheduled task id.
  */
 FileCopyManager.prototype.deleteEntries = function(entries, callback) {
   var id = ++this.lastDeleteId_;
   var task = {
     entries: entries,
     id: id,
     timeout: setTimeout(this.forceDeleteTask.bind(this, id),
         FileCopyManager.DELETE_TIMEOUT)
   };
   this.deleteTasks_.push(task);
   this.maybeScheduleCloseBackgroundPage_();
   callback(id);
   this.sendDeleteEvent_(task, 'SCHEDULED');
 };
 
 /**
  * Creates a zip file for the selection of files.
+ *
  * @param {Entry} dirEntry the directory containing the selection.
  * @param {boolean} isOnDrive If directory is on Drive.
  * @param {Array.<Entry>} selectionEntries the selected entries.
  */
 FileCopyManager.prototype.zipSelection = function(dirEntry, isOnDrive,
                                                   selectionEntries) {
   var self = this;
   var zipTask = new FileCopyManager.Task(dirEntry, dirEntry);
   zipTask.zip = true;
   zipTask.sourceOnDrive = isOnDrive;
@@ skipping 10 matching lines @@
     } else {
       // Force to update the progress of butter bar when there are new tasks
       // coming while servicing current task.
       self.sendProgressEvent_('PROGRESS');
     }
   });
 };
 
 /**
  * Force deletion before timeout runs out.
+ *
  * @param {number} id The delete task id (as returned by deleteEntries).
  */
 FileCopyManager.prototype.forceDeleteTask = function(id) {
   var task = this.findDeleteTaskAndCancelTimeout_(id);
   if (task) this.serviceDeleteTask_(task);
 };
 
 /**
  * Cancels the scheduled deletion.
+ *
  * @param {number} id The delete task id (as returned by deleteEntries).
  */
 FileCopyManager.prototype.cancelDeleteTask = function(id) {
   var task = this.findDeleteTaskAndCancelTimeout_(id);
   if (task) this.sendDeleteEvent_(task, 'CANCELLED');
 };
 
 /**
  * Finds the delete task, removes it from list and cancels the timeout.
+ *
  * @param {number} id The delete task id (as returned by deleteEntries).
  * @return {object} The delete task.
  * @private
  */
 FileCopyManager.prototype.findDeleteTaskAndCancelTimeout_ = function(id) {
   for (var index = 0; index < this.deleteTasks_.length; index++) {
     var task = this.deleteTasks_[index];
     if (task.id == id) {
       this.deleteTasks_.splice(index, 1);
       this.maybeScheduleCloseBackgroundPage_();
       if (task.timeout) {
         clearTimeout(task.timeout);
         task.timeout = null;
       }
       return task;
     }
   }
   return null;
 };
 
 /**
  * Performs the deletion.
+ *
  * @param {object} task The delete task (see deleteEntries function).
  * @private

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

Here we have as the last one. That's why my concern.

  */
 FileCopyManager.prototype.serviceDeleteTask_ = function(task) {
   var downcount = task.entries.length + 1;
 
   var onComplete = function() {
     if (--downcount == 0)
       this.sendDeleteEvent_(task, 'SUCCESS');
   }.bind(this);
 
   for (var i = 0; i < task.entries.length; i++) {
     var entry = task.entries[i];
     util.removeFileOrDirectory(
         entry,
         onComplete,
         onComplete); // We ignore error, because we can't do anything here.
   }
   onComplete();
 };
 
 /**
  * Send a 'delete' event to listeners.
+ *
  * @param {Object} task The delete task (see deleteEntries function).
  * @param {string} reason Event reason.
  * @private
  */
 FileCopyManager.prototype.sendDeleteEvent_ = function(task, reason) {
   this.sendEvent_('delete', {
     reason: reason,
     id: task.id,
     urls: task.entries.map(function(e) {
       return util.makeFilesystemUrl(e.fullPath);
     })
   });
 };