From 0f3e6cb50af06bf3a64ea7f1abd360c53fa0bf8c Mon Sep 17 00:00:00 2001 From: Vincent Petry Date: Mon, 23 Jun 2014 23:56:10 +0200 Subject: [PATCH] Improved Javascript docs for JSDoc Added namespaces so that JSDoc can find them. Fixed a few warnings. Improved some comments. --- apps/files/js/app.js | 25 ++++- apps/files/js/breadcrumb.js | 28 ++++- apps/files/js/file-upload.js | 2 +- apps/files/js/fileactions.js | 41 ++++++- apps/files/js/filelist.js | 133 ++++++++++++++++++----- apps/files/js/files.js | 5 +- apps/files/js/filesummary.js | 7 +- apps/files/js/navigation.js | 11 ++ apps/files/js/upload.js | 1 - apps/files_encryption/js/encryption.js | 4 + apps/files_external/js/app.js | 6 + apps/files_external/js/mountsfilelist.js | 33 +++++- apps/files_sharing/js/app.js | 6 + apps/files_sharing/js/public.js | 8 ++ apps/files_sharing/js/share.js | 18 ++- apps/files_sharing/js/sharedfilelist.js | 52 ++++++++- apps/files_trashbin/js/app.js | 6 + apps/files_trashbin/js/filelist.js | 19 +++- apps/files_versions/js/versions.js | 2 + core/js/config.js | 3 + core/js/eventsource.js | 21 ++++ core/js/js.js | 42 +++++-- core/js/oc-dialogs.js | 1 + 23 files changed, 403 insertions(+), 71 deletions(-) diff --git a/apps/files/js/app.js b/apps/files/js/app.js index 89098e3a8a..ee5330485e 100644 --- a/apps/files/js/app.js +++ b/apps/files/js/app.js @@ -15,12 +15,34 @@ (function() { if (!OCA.Files) { + /** + * Namespace for the files app + * @namespace OCA.Files + */ OCA.Files = {}; } - var App = { + /** + * @namespace OCA.Files.App + */ + OCA.Files.App = { + /** + * Navigation control + * + * @member {OCA.Files.Navigation} + */ navigation: null, + /** + * File list for the "All files" section. + * + * @member {OCA.Files.FileList} + */ + fileList: null, + + /** + * Initializes the files app + */ initialize: function() { this.navigation = new OCA.Files.Navigation($('#app-navigation')); @@ -191,7 +213,6 @@ OC.Util.History.pushState(params); } }; - OCA.Files.App = App; })(); $(document).ready(function() { diff --git a/apps/files/js/breadcrumb.js b/apps/files/js/breadcrumb.js index 8df9b7ee6f..af4e48c8f8 100644 --- a/apps/files/js/breadcrumb.js +++ b/apps/files/js/breadcrumb.js @@ -19,10 +19,17 @@ * */ -/* global OC */ (function() { /** - * Creates an breadcrumb element in the given container + * @class BreadCrumb + * @memberof OCA.Files + * @classdesc Breadcrumbs that represent the current path. + * + * @param {Object} [options] options + * @param {Function} [options.onClick] click event handler + * @param {Function} [options.onDrop] drop event handler + * @param {Function} [options.getCrumbUrl] callback that returns + * the URL of a given breadcrumb */ var BreadCrumb = function(options){ this.$el = $('
'); @@ -37,12 +44,17 @@ this.getCrumbUrl = options.getCrumbUrl; } }; + /** + * @memberof OCA.Files + */ BreadCrumb.prototype = { $el: null, dir: null, /** * Total width of all breadcrumbs + * @type int + * @private */ totalWidth: 0, breadcrumbs: [], @@ -64,8 +76,9 @@ /** * Returns the full URL to the given directory - * @param part crumb data as map - * @param index crumb index + * + * @param {Object.} part crumb data as map + * @param {int} index crumb index * @return full URL */ getCrumbUrl: function(part, index) { @@ -121,8 +134,9 @@ /** * Makes a breadcrumb structure based on the given path - * @param dir path to split into a breadcrumb structure - * @return array of map {dir: path, name: displayName} + * + * @param {String} dir path to split into a breadcrumb structure + * @return {Object.} map of {dir: path, name: displayName} */ _makeCrumbs: function(dir) { var crumbs = []; @@ -166,6 +180,8 @@ /** * Show/hide breadcrumbs to fit the given width + * + * @param {int} availableWidth available width */ setMaxWidth: function (availableWidth) { if (this.availableWidth !== availableWidth) { diff --git a/apps/files/js/file-upload.js b/apps/files/js/file-upload.js index 460c243564..ab450dc5ca 100644 --- a/apps/files/js/file-upload.js +++ b/apps/files/js/file-upload.js @@ -49,7 +49,7 @@ function supportAjaxUploadWithProgress() { /** * keeps track of uploads in progress and implements callbacks for the conflicts dialog - * @type {OC.Upload} + * @namespace */ OC.Upload = { _uploads: [], diff --git a/apps/files/js/fileactions.js b/apps/files/js/fileactions.js index 8ae0d8f1b2..f15ad744b7 100644 --- a/apps/files/js/fileactions.js +++ b/apps/files/js/fileactions.js @@ -13,11 +13,14 @@ /** * Construct a new FileActions instance + * @constructs FileActions + * @memberof OCA.Files */ var FileActions = function() { this.initialize(); - } + }; FileActions.prototype = { + /** @lends FileActions.prototype */ actions: {}, defaults: {}, icons: {}, @@ -31,9 +34,14 @@ /** * List of handlers to be notified whenever a register() or * setDefault() was called. + * + * @member {Function[]} */ _updateListeners: {}, + /** + * @private + */ initialize: function() { this.clear(); // abusing jquery for events until we get a real event lib @@ -45,7 +53,7 @@ * Adds an event handler * * @param {String} eventName event name - * @param Function callback + * @param {Function} callback */ on: function(eventName, callback) { this.$el.on(eventName, callback); @@ -75,7 +83,7 @@ * Merges the actions from the given fileActions into * this instance. * - * @param fileActions instance of OCA.Files.FileActions + * @param {OCA.Files.FileActions} fileActions instance of OCA.Files.FileActions */ merge: function(fileActions) { var self = this; @@ -113,8 +121,9 @@ * to the name given in action.name * @param {String} action.mime mime type * @param {int} action.permissions permissions - * @param {(Function|String)} action.icon icon - * @param {Function} action.actionHandler function that performs the action + * @param {(Function|String)} action.icon icon path to the icon or function + * that returns it + * @param {OCA.Files.FileActions~actionHandler} action.actionHandler action handler function */ registerAction: function (action) { var mime = action.mime; @@ -130,6 +139,9 @@ this.icons[name] = action.icon; this._notifyUpdateListeners('registerAction', {action: action}); }, + /** + * Clears all registered file actions. + */ clear: function() { this.actions = {}; this.defaults = {}; @@ -137,6 +149,12 @@ this.currentFile = null; this._updateListeners = []; }, + /** + * Sets the default action for a given mime type. + * + * @param {String} mime mime type + * @param {String} name action name + */ setDefault: function (mime, name) { this.defaults[mime] = name; this._notifyUpdateListeners('setDefault', {defaultAction: {mime: mime, name: name}}); @@ -370,6 +388,18 @@ OCA.Files.FileActions = FileActions; + /** + * Action handler function for file actions + * + * @callback OCA.Files.FileActions~actionHandler + * @param {String} fileName name of the clicked file + * @param context context + * @param {String} context.dir directory of the file + * @param context.$file jQuery element of the file + * @param {OCA.Files.FileList} context.fileList the FileList instance on which the action occurred + * @param {OCA.Files.FileActions} context.fileActions the FileActions instance on which the action occurred + */ + // global file actions to be used by all lists OCA.Files.fileActions = new OCA.Files.FileActions(); OCA.Files.legacyFileActions = new OCA.Files.FileActions(); @@ -380,6 +410,7 @@ // their actions on. Since legacy apps are very likely to break with other // FileList views than the main one ("All files"), actions registered // through window.FileActions will be limited to the main file list. + // @deprecated use OCA.Files.FileActions instead window.FileActions = OCA.Files.legacyFileActions; window.FileActions.register = function (mime, name, permissions, icon, action, displayName) { console.warn('FileActions.register() is deprecated, please use OCA.Files.fileActions.register() instead', arguments); diff --git a/apps/files/js/filelist.js b/apps/files/js/filelist.js index cf1d9780d9..bec0155e90 100644 --- a/apps/files/js/filelist.js +++ b/apps/files/js/filelist.js @@ -10,13 +10,26 @@ (function() { /** + * @class OCA.Files.FileList + * @classdesc + * * The FileList class manages a file list view. * A file list view consists of a controls bar and * a file list table. + * + * @param $el container element with existing markup for the #controls + * and a table + * @param [options] map of options, see other parameters + * @param [options.scrollContainer] scrollable container, defaults to $(window) + * @param [options.dragOptions] drag options, disabled by default + * @param [options.folderDropOptions] folder drop options, disabled by default */ var FileList = function($el, options) { this.initialize($el, options); }; + /** + * @memberof OCA.Files + */ FileList.prototype = { SORT_INDICATOR_ASC_CLASS: 'icon-triangle-n', SORT_INDICATOR_DESC_CLASS: 'icon-triangle-s', @@ -41,15 +54,27 @@ */ $fileList: null, + /** + * @type OCA.Files.BreadCrumb + */ breadcrumb: null, /** - * Instance of FileSummary + * @type OCA.Files.FileSummary */ fileSummary: null, + + /** + * Whether the file list was initialized already. + * @type boolean + */ initialized: false, - // number of files per page, calculated dynamically + /** + * Number of files per page + * + * @return {int} page size + */ pageSize: function() { return Math.ceil(this.$container.height() / 50); }, @@ -57,37 +82,44 @@ /** * Array of files in the current folder. * The entries are of file data. + * + * @type Array. */ files: [], /** * File actions handler, defaults to OCA.Files.FileActions + * @type OCA.Files.FileActions */ fileActions: null, /** * Map of file id to file data + * @type Object. */ _selectedFiles: {}, /** * Summary of selected files. - * Instance of FileSummary. + * @type OCA.Files.FileSummary */ _selectionSummary: null, /** * Sort attribute + * @type String */ _sort: 'name', /** * Sort direction: 'asc' or 'desc' + * @type String */ _sortDirection: 'asc', /** * Sort comparator function for the current sort + * @type Function */ _sortComparator: null, @@ -100,6 +132,7 @@ /** * Current directory + * @type String */ _currentDirectory: null, @@ -116,6 +149,7 @@ * @param options.dragOptions drag options, disabled by default * @param options.folderDropOptions folder drop options, disabled by default * @param options.scrollTo name of file to scroll to after the first load + * @private */ initialize: function($el, options) { var self = this; @@ -192,6 +226,11 @@ this.fileActions.off('setDefault', this._onFileActionsUpdated); }, + /** + * Initializes the file actions, set up listeners. + * + * @param {OCA.Files.FileActions} fileActions file actions + */ _initFileActions: function(fileActions) { this.fileActions = fileActions; if (!this.fileActions) { @@ -588,8 +627,8 @@ }, /** * Creates a new table row element using the given file data. - * @param fileData map of file attributes - * @param options map of attribute "loading" whether the entry is currently loading + * @param {OCA.Files.FileInfo} fileData file info attributes + * @param options map of attributes * @return new tr element (not appended to the table) */ _createRow: function(fileData, options) { @@ -728,12 +767,14 @@ * Adds an entry to the files array and also into the DOM * in a sorted manner. * - * @param fileData map of file attributes - * @param options map of attributes: - * @param options.updateSummary true to update the summary after adding (default), false otherwise - * @param options.silent true to prevent firing events like "fileActionsReady" - * @param options.animate true to animate preview loading (defaults to true here) - * @param options.scrollTo true to automatically scroll to the file's location + * @param {OCA.Files.FileInfo} fileData map of file attributes + * @param {Object} [options] map of attributes + * @param {boolean} [options.updateSummary] true to update the summary + * after adding (default), false otherwise. Defaults to true. + * @param {boolean} [options.silent] true to prevent firing events like "fileActionsReady", + * defaults to false. + * @param {boolean} [options.animate] true to animate the thumbnail image after load + * defaults to true. * @return new tr element (not appended to the table) */ add: function(fileData, options) { @@ -799,11 +840,13 @@ * Creates a new row element based on the given attributes * and returns it. * - * @param fileData map of file attributes - * @param options map of attributes: - * - "index" optional index at which to insert the element - * - "updateSummary" true to update the summary after adding (default), false otherwise - * - "animate" true to animate the preview rendering + * @param {OCA.Files.FileInfo} fileData map of file attributes + * @param {Object} [options] map of attributes + * @param {int} [options.index] index at which to insert the element + * @param {boolean} [options.updateSummary] true to update the summary + * after adding (default), false otherwise. Defaults to true. + * @param {boolean} [options.animate] true to animate the thumbnail image after load + * defaults to true. * @return new tr element (not appended to the table) */ _renderRow: function(fileData, options) { @@ -870,6 +913,7 @@ }, /** * Returns the current directory + * @method getCurrentDirectory * @return current directory */ getCurrentDirectory: function(){ @@ -1051,7 +1095,10 @@ /** * Generates a preview URL based on the URL space. - * @param urlSpec map with {x: width, y: height, file: file path} + * @param urlSpec attributes for the URL + * @param {int} urlSpec.x width + * @param {int} urlSpec.y height + * @param {String} urlSpec.file path to the file * @return preview URL */ generatePreviewUrl: function(urlSpec) { @@ -1158,8 +1205,9 @@ /** * Removes a file entry from the list * @param name name of the file to remove - * @param options optional options as map: - * "updateSummary": true to update the summary (default), false otherwise + * @param {Object} [options] map of attributes + * @param {boolean} [options.updateSummary] true to update the summary + * after removing, false otherwise. Defaults to true. * @return deleted element */ remove: function(name, options){ @@ -1201,6 +1249,8 @@ * Finds the index of the row before which the given * fileData should be inserted, considering the current * sorting + * + * @param {OCA.Files.FileInfo} fileData file info */ _findInsertionIndex: function(fileData) { var index = 0; @@ -1515,7 +1565,7 @@ /** * Shows the loading mask. * - * @see #hideMask + * @see OCA.Files.FileList#hideMask */ showMask: function() { // in case one was shown before @@ -1536,7 +1586,7 @@ }, /** * Hide the loading mask. - * @see #showMask + * @see OCA.Files.FileList#showMask */ hideMask: function() { this.$el.find('.mask').remove(); @@ -1961,15 +2011,17 @@ /** * Sort comparators. + * @namespace OCA.Files.FileList.Comparators + * @private */ FileList.Comparators = { /** * Compares two file infos by name, making directories appear * first. * - * @param fileInfo1 file info - * @param fileInfo2 file info - * @return -1 if the first file must appear before the second one, + * @param {OCA.Files.FileInfo} fileInfo1 file info + * @param {OCA.Files.FileInfo} fileInfo2 file info + * @return {int} -1 if the first file must appear before the second one, * 0 if they are identify, 1 otherwise. */ name: function(fileInfo1, fileInfo2) { @@ -1984,9 +2036,9 @@ /** * Compares two file infos by size. * - * @param fileInfo1 file info - * @param fileInfo2 file info - * @return -1 if the first file must appear before the second one, + * @param {OCA.Files.FileInfo} fileInfo1 file info + * @param {OCA.Files.FileInfo} fileInfo2 file info + * @return {int} -1 if the first file must appear before the second one, * 0 if they are identify, 1 otherwise. */ size: function(fileInfo1, fileInfo2) { @@ -1995,9 +2047,9 @@ /** * Compares two file infos by timestamp. * - * @param fileInfo1 file info - * @param fileInfo2 file info - * @return -1 if the first file must appear before the second one, + * @param {OCA.Files.FileInfo} fileInfo1 file info + * @param {OCA.Files.FileInfo} fileInfo2 file info + * @return {int} -1 if the first file must appear before the second one, * 0 if they are identify, 1 otherwise. */ mtime: function(fileInfo1, fileInfo2) { @@ -2005,6 +2057,27 @@ } }; + /** + * File info attributes. + * + * @todo make this a real class in the future + * @typedef {Object} OCA.Files.FileInfo + * + * @property {int} id file id + * @property {String} name file name + * @property {String} [path] file path, defaults to the list's current path + * @property {String} mimetype mime type + * @property {String} type "file" for files or "dir" for directories + * @property {int} permissions file permissions + * @property {int} mtime modification time in milliseconds + * @property {boolean} [isShareMountPoint] whether the file is a share mount + * point + * @property {boolean} [isPreviewAvailable] whether a preview is available + * for the given file type + * @property {String} [icon] path to the mime type icon + * @property {String} etag etag of the file + */ + OCA.Files.FileList = FileList; })(); diff --git a/apps/files/js/files.js b/apps/files/js/files.js index df268fea6d..b11ef03eab 100644 --- a/apps/files/js/files.js +++ b/apps/files/js/files.js @@ -195,7 +195,10 @@ /** * Generates a preview URL based on the URL space. - * @param urlSpec map with {x: width, y: height, file: file path} + * @param urlSpec attributes for the URL + * @param {int} urlSpec.x width + * @param {int} urlSpec.y height + * @param {String} urlSpec.file path to the file * @return preview URL * @deprecated used OCA.Files.FileList.generatePreviewUrl instead */ diff --git a/apps/files/js/filesummary.js b/apps/files/js/filesummary.js index ca70259335..f83eb54678 100644 --- a/apps/files/js/filesummary.js +++ b/apps/files/js/filesummary.js @@ -19,14 +19,15 @@ * */ -/* global OC, n, t */ - (function() { /** * The FileSummary class encapsulates the file summary values and * the logic to render it in the given container + * + * @constructs FileSummary + * @memberof OCA.Files + * * @param $tr table row element - * $param summary optional initial summary value */ var FileSummary = function($tr) { this.$el = $tr; diff --git a/apps/files/js/navigation.js b/apps/files/js/navigation.js index b959e016e8..be385f21f5 100644 --- a/apps/files/js/navigation.js +++ b/apps/files/js/navigation.js @@ -13,10 +13,19 @@ (function() { + /** + * @class OCA.Files.Navigation + * @classdesc Navigation control for the files app sidebar. + * + * @param $el element containing the navigation + */ var Navigation = function($el) { this.initialize($el); }; + /** + * @memberof OCA.Files + */ Navigation.prototype = { /** @@ -31,6 +40,8 @@ /** * Initializes the navigation from the given container + * + * @private * @param $el element containing the navigation */ initialize: function($el) { diff --git a/apps/files/js/upload.js b/apps/files/js/upload.js index 617cf4b1c1..518608615e 100644 --- a/apps/files/js/upload.js +++ b/apps/files/js/upload.js @@ -8,7 +8,6 @@ * */ -/* global OC */ function Upload(fileSelector) { if ($.support.xhrFileUpload) { return new XHRUpload(fileSelector.target.files); diff --git a/apps/files_encryption/js/encryption.js b/apps/files_encryption/js/encryption.js index 65ffabe55e..d2d1c3a1fc 100644 --- a/apps/files_encryption/js/encryption.js +++ b/apps/files_encryption/js/encryption.js @@ -5,6 +5,10 @@ * See the COPYING-README file. */ +/** + * @namespace + * @memberOf OC + */ OC.Encryption={ MIGRATION_OPEN:0, MIGRATION_COMPLETED:1, diff --git a/apps/files_external/js/app.js b/apps/files_external/js/app.js index 58ad1a0f6e..bf853f926d 100644 --- a/apps/files_external/js/app.js +++ b/apps/files_external/js/app.js @@ -9,8 +9,14 @@ */ if (!OCA.External) { + /** + * @namespace + */ OCA.External = {}; } +/** + * @namespace + */ OCA.External.App = { fileList: null, diff --git a/apps/files_external/js/mountsfilelist.js b/apps/files_external/js/mountsfilelist.js index 20bf0f785d..c45faafd9b 100644 --- a/apps/files_external/js/mountsfilelist.js +++ b/apps/files_external/js/mountsfilelist.js @@ -10,15 +10,29 @@ (function() { /** - * External storage file list - */ + * @class OCA.External.FileList + * @augments OCA.Files.FileList + * + * @classdesc External storage file list. + * + * Displays a list of mount points visible + * for the current user. + * + * @param $el container element with existing markup for the #controls + * and a table + * @param [options] map of options, see other parameters + **/ var FileList = function($el, options) { this.initialize($el, options); }; - FileList.prototype = _.extend({}, OCA.Files.FileList.prototype, { + FileList.prototype = _.extend({}, OCA.Files.FileList.prototype, + /** @lends OCA.External.FileList.prototype */ { appName: 'External storage', + /** + * @private + */ initialize: function($el, options) { OCA.Files.FileList.prototype.initialize.apply(this, arguments); if (this.initialized) { @@ -26,6 +40,9 @@ } }, + /** + * @param {OCA.External.MountPointInfo} fileData + */ _createRow: function(fileData) { // TODO: hook earlier and render the whole row here var $tr = OCA.Files.FileList.prototype._createRow.apply(this, arguments); @@ -114,5 +131,15 @@ } }); + /** + * Mount point info attributes. + * + * @typedef {Object} OCA.External.MountPointInfo + * + * @property {String} name mount point name + * @property {String} scope mount point scope "personal" or "system" + * @property {String} backend external storage backend name + */ + OCA.External.FileList = FileList; })(); diff --git a/apps/files_sharing/js/app.js b/apps/files_sharing/js/app.js index 1a3bfac5b9..1314304c56 100644 --- a/apps/files_sharing/js/app.js +++ b/apps/files_sharing/js/app.js @@ -9,8 +9,14 @@ */ if (!OCA.Sharing) { + /** + * @namespace OCA.Sharing + */ OCA.Sharing = {}; } +/** + * @namespace + */ OCA.Sharing.App = { _inFileList: null, diff --git a/apps/files_sharing/js/public.js b/apps/files_sharing/js/public.js index c4b5508692..52679a7158 100644 --- a/apps/files_sharing/js/public.js +++ b/apps/files_sharing/js/public.js @@ -16,9 +16,17 @@ if (!OCA.Sharing) { if (!OCA.Files) { OCA.Files = {}; } +/** + * @namespace + */ OCA.Sharing.PublicApp = { _initialized: false, + /** + * Initializes the public share app. + * + * @param $el container + */ initialize: function ($el) { var self = this; var fileActions; diff --git a/apps/files_sharing/js/share.js b/apps/files_sharing/js/share.js index eccd21c924..36ae878008 100644 --- a/apps/files_sharing/js/share.js +++ b/apps/files_sharing/js/share.js @@ -12,7 +12,19 @@ if (!OCA.Sharing) { OCA.Sharing = {}; } + /** + * @namespace + */ OCA.Sharing.Util = { + /** + * Initialize the sharing app overrides of the default + * file list. + * + * Registers the "Share" file action and adds additional + * DOM attributes for the sharing file info. + * + * @param {OCA.Files.FileActions} fileActions file actions to extend + */ initialize: function(fileActions) { if (OCA.Files.FileList) { var oldCreateRow = OCA.Files.FileList.prototype._createRow; @@ -160,9 +172,9 @@ * other ones will be shown as "+x" where "x" is the number of * remaining recipients. * - * @param recipients recipients array - * @param count optional total recipients count (in case the array was shortened) - * @return formatted recipients display text + * @param {Array.} recipients recipients array + * @param {int} count optional total recipients count (in case the array was shortened) + * @return {String} formatted recipients display text */ formatRecipients: function(recipients, count) { var maxRecipients = 4; diff --git a/apps/files_sharing/js/sharedfilelist.js b/apps/files_sharing/js/sharedfilelist.js index b99611f9bf..5869d7f77f 100644 --- a/apps/files_sharing/js/sharedfilelist.js +++ b/apps/files_sharing/js/sharedfilelist.js @@ -10,15 +10,25 @@ (function() { /** - * Sharing file list + * @class OCA.Sharing.FileList + * @augments OCA.Files.FileList * + * @classdesc Sharing file list. * Contains both "shared with others" and "shared with you" modes. + * + * @param $el container element with existing markup for the #controls + * and a table + * @param [options] map of options, see other parameters + * @param {boolean} [options.sharedWithUser] true to return files shared with + * the current user, false to return files that the user shared with others. + * Defaults to false. + * @param {boolean} [options.linksOnly] true to return only link shares */ var FileList = function($el, options) { this.initialize($el, options); }; - - FileList.prototype = _.extend({}, OCA.Files.FileList.prototype, { + FileList.prototype = _.extend({}, OCA.Files.FileList.prototype, + /** @lends OCA.Sharing.FileList.prototype */ { appName: 'Shares', /** @@ -27,9 +37,11 @@ */ _sharedWithUser: false, _linksOnly: false, - _clientSideSort: true, + /** + * @private + */ initialize: function($el, options) { OCA.Files.FileList.prototype.initialize.apply(this, arguments); if (this.initialized) { @@ -138,8 +150,8 @@ /** * Converts the OCS API share response data to a file info * list - * @param OCS API share array - * @return array of file info maps + * @param {Array} data OCS API share array + * @return {Array.} array of shared file info */ _makeFilesFromShares: function(data) { /* jshint camelcase: false */ @@ -259,5 +271,33 @@ } }); + /** + * Share info attributes. + * + * @typedef {Object} OCA.Sharing.ShareInfo + * + * @property {int} id share ID + * @property {int} type share type + * @property {String} target share target, either user name or group name + * @property {int} stime share timestamp in milliseconds + * @property {String} [targetDisplayName] display name of the recipient + * (only when shared with others) + * + */ + + /** + * Shared file info attributes. + * + * @typedef {OCA.Files.FileInfo} OCA.Sharing.SharedFileInfo + * + * @property {Array.} shares array of shares for + * this file + * @property {int} mtime most recent share time (if multiple shares) + * @property {String} shareOwner name of the share owner + * @property {Array.} recipients name of the first 4 recipients + * (this is mostly for display purposes) + * @property {String} recipientsDisplayName display name + */ + OCA.Sharing.FileList = FileList; })(); diff --git a/apps/files_trashbin/js/app.js b/apps/files_trashbin/js/app.js index 376ee7b01c..a9727542ba 100644 --- a/apps/files_trashbin/js/app.js +++ b/apps/files_trashbin/js/app.js @@ -8,7 +8,13 @@ * */ +/** + * @namespace OCA.Trashbin + */ OCA.Trashbin = {}; +/** + * @namespace OCA.Trashbin.App + */ OCA.Trashbin.App = { _initialized: false, diff --git a/apps/files_trashbin/js/filelist.js b/apps/files_trashbin/js/filelist.js index b8688d8976..a3631a2d0f 100644 --- a/apps/files_trashbin/js/filelist.js +++ b/apps/files_trashbin/js/filelist.js @@ -14,8 +14,8 @@ * Convert a file name in the format filename.d12345 to the real file name. * This will use basename. * The name will not be changed if it has no ".d12345" suffix. - * @param name file name - * @return converted file name + * @param {String} name file name + * @return {String} converted file name */ function getDeletedFileName(name) { name = OC.basename(name); @@ -26,13 +26,26 @@ return name; } + /** + * @class OCA.Trashbin.FileList + * @augments OCA.Files.FileList + * @classdesc List of deleted files + * + * @param $el container element with existing markup for the #controls + * and a table + * @param [options] map of options + */ var FileList = function($el, options) { this.initialize($el, options); }; - FileList.prototype = _.extend({}, OCA.Files.FileList.prototype, { + FileList.prototype = _.extend({}, OCA.Files.FileList.prototype, + /** @lends OCA.Trashbin.FileList.prototype */ { id: 'trashbin', appName: t('files_trashbin', 'Deleted files'), + /** + * @private + */ initialize: function() { var result = OCA.Files.FileList.prototype.initialize.apply(this, arguments); this.$el.find('.undelete').click('click', _.bind(this._onClickRestoreSelected, this)); diff --git a/apps/files_versions/js/versions.js b/apps/files_versions/js/versions.js index 64e0df7649..1a47c1749f 100644 --- a/apps/files_versions/js/versions.js +++ b/apps/files_versions/js/versions.js @@ -11,6 +11,8 @@ /* global scanFiles, escapeHTML, formatDate */ $(document).ready(function(){ + // TODO: namespace all this as OCA.FileVersions + if ($('#isPublic').val()){ // no versions actions in public mode // beware of https://github.com/owncloud/core/issues/4545 diff --git a/core/js/config.js b/core/js/config.js index 52d1c3aee2..b034b7e8cd 100644 --- a/core/js/config.js +++ b/core/js/config.js @@ -4,6 +4,9 @@ * See the COPYING-README file. */ +/** + * @namespace + */ OC.AppConfig={ url:OC.filePath('core','ajax','appconfig.php'), getCall:function(action,data,callback){ diff --git a/core/js/eventsource.js b/core/js/eventsource.js index 46bd9f60bb..6f23cebb68 100644 --- a/core/js/eventsource.js +++ b/core/js/eventsource.js @@ -34,6 +34,8 @@ * Create a new event source * @param {string} src * @param {object} [data] to be send as GET + * + * @constructs OC.EventSource */ OC.EventSource=function(src,data){ var dataStr=''; @@ -92,6 +94,16 @@ OC.EventSource.prototype={ iframe:null, listeners:{},//only for fallback useFallBack:false, + /** + * Fallback callback for browsers that don't have the + * native EventSource object. + * + * Calls the registered listeners. + * + * @private + * @param {String} type event type + * @param {Object} data received data + */ fallBackCallBack:function(type,data){ var i; // ignore messages that might appear after closing @@ -111,6 +123,12 @@ OC.EventSource.prototype={ } }, lastLength:0,//for fallback + /** + * Listen to a given type of events. + * + * @param {String} type event type + * @param {Function} callback event callback + */ listen:function(type,callback){ if(callback && callback.call){ @@ -134,6 +152,9 @@ OC.EventSource.prototype={ } } }, + /** + * Closes this event source. + */ close:function(){ this.closed = true; if (typeof this.source !== 'undefined') { diff --git a/core/js/js.js b/core/js/js.js index b1a61ddf50..39e382b544 100644 --- a/core/js/js.js +++ b/core/js/js.js @@ -5,6 +5,7 @@ * To the end of config/config.php to enable debug mode. * The undefined checks fix the broken ie8 console */ + var oc_debug; var oc_webroot; @@ -57,6 +58,7 @@ function fileDownloadPath(dir, file) { return OC.filePath('files', 'ajax', 'download.php')+'?files='+encodeURIComponent(file)+'&dir='+encodeURIComponent(dir); } +/** @namespace */ var OC={ PERMISSION_CREATE:4, PERMISSION_READ:1, @@ -251,14 +253,22 @@ var OC={ }, /** - * @todo Write the documentation + * Returns the base name of the given path. + * For example for "/abc/somefile.txt" it will return "somefile.txt" + * + * @param {String} path + * @return {String} base name */ basename: function(path) { return path.replace(/\\/g,'/').replace( /.*\//, '' ); }, /** - * @todo Write the documentation + * Returns the dir name of the given path. + * For example for "/abc/somefile.txt" it will return "/abc" + * + * @param {String} path + * @return {String} dir name */ dirname: function(path) { return path.replace(/\\/g,'/').replace(/\/[^\/]*$/, ''); @@ -277,12 +287,16 @@ var OC={ }); } }, 500), + /** + * Dialog helper for jquery dialogs. + * + * @namespace OC.dialogs + */ dialogs:OCdialogs, - /** * Parses a URL query string into a JS map * @param {string} queryString query string in the format param1=1234¶m2=abcde¶m3=xyz - * @return map containing key/values matching the URL parameters + * @return {Object.} map containing key/values matching the URL parameters */ parseQueryString:function(queryString){ var parts, @@ -334,7 +348,7 @@ var OC={ /** * Builds a URL query from a JS map. - * @param params parameter map + * @param {Object.} params map containing key/values matching the URL parameters * @return {string} String containing a URL query (without question) mark */ buildQueryString: function(params) { @@ -454,7 +468,7 @@ var OC={ * * This is makes it possible for unit tests to * stub matchMedia (which doesn't work in PhantomJS) - * @todo Write documentation + * @private */ _matchMedia: function(media) { if (window.matchMedia) { @@ -464,6 +478,9 @@ var OC={ } }; +/** + * @namespace OC.search + */ OC.search.customResults={}; OC.search.currentResult=-1; OC.search.lastQuery=''; @@ -531,6 +548,7 @@ OC.msg={ /** * @todo Write documentation + * @namespace */ OC.Notification={ queuedNotifications: [], @@ -607,7 +625,12 @@ OC.Notification={ }; /** - * @todo Write documentation + * Breadcrumb class + * + * @namespace + * + * @deprecated will be replaced by the breadcrumb implementation + * of the files app in the future */ OC.Breadcrumb={ container:null, @@ -721,6 +744,7 @@ OC.Breadcrumb={ if(typeof localStorage !=='undefined' && localStorage !== null){ /** * User and instance aware localstorage + * @namespace */ OC.localStorage={ namespace:'oc_'+OC.currentUser+'_'+OC.webroot+'_', @@ -1164,6 +1188,7 @@ function relative_modified_date(timestamp) { /** * Utility functions + * @namespace */ OC.Util = { // TODO: remove original functions from global namespace @@ -1314,6 +1339,8 @@ OC.Util = { * Utility class for the history API, * includes fallback to using the URL hash when * the browser doesn't support the history API. + * + * @namespace */ OC.Util.History = { _handlers: [], @@ -1473,6 +1500,7 @@ OC.set=function(name, value) { /** * Namespace for apps + * @namespace OCA */ window.OCA = {}; diff --git a/core/js/oc-dialogs.js b/core/js/oc-dialogs.js index bd6fd2e500..9e5afea1a6 100644 --- a/core/js/oc-dialogs.js +++ b/core/js/oc-dialogs.js @@ -23,6 +23,7 @@ /** * this class to ease the usage of jquery dialogs + * @lends OC.dialogs */ var OCdialogs = { // dialog button types