Improved Javascript docs for JSDoc

Added namespaces so that JSDoc can find them.
Fixed a few warnings.
Improved some comments.
This commit is contained in:
Vincent Petry 2014-06-23 23:56:10 +02:00
parent c7dc656b2b
commit 0f3e6cb50a
23 changed files with 403 additions and 71 deletions

View File

@ -15,12 +15,34 @@
(function() { (function() {
if (!OCA.Files) { if (!OCA.Files) {
/**
* Namespace for the files app
* @namespace OCA.Files
*/
OCA.Files = {}; OCA.Files = {};
} }
var App = { /**
* @namespace OCA.Files.App
*/
OCA.Files.App = {
/**
* Navigation control
*
* @member {OCA.Files.Navigation}
*/
navigation: null, navigation: null,
/**
* File list for the "All files" section.
*
* @member {OCA.Files.FileList}
*/
fileList: null,
/**
* Initializes the files app
*/
initialize: function() { initialize: function() {
this.navigation = new OCA.Files.Navigation($('#app-navigation')); this.navigation = new OCA.Files.Navigation($('#app-navigation'));
@ -191,7 +213,6 @@
OC.Util.History.pushState(params); OC.Util.History.pushState(params);
} }
}; };
OCA.Files.App = App;
})(); })();
$(document).ready(function() { $(document).ready(function() {

View File

@ -19,10 +19,17 @@
* *
*/ */
/* global OC */
(function() { (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){ var BreadCrumb = function(options){
this.$el = $('<div class="breadcrumb"></div>'); this.$el = $('<div class="breadcrumb"></div>');
@ -37,12 +44,17 @@
this.getCrumbUrl = options.getCrumbUrl; this.getCrumbUrl = options.getCrumbUrl;
} }
}; };
/**
* @memberof OCA.Files
*/
BreadCrumb.prototype = { BreadCrumb.prototype = {
$el: null, $el: null,
dir: null, dir: null,
/** /**
* Total width of all breadcrumbs * Total width of all breadcrumbs
* @type int
* @private
*/ */
totalWidth: 0, totalWidth: 0,
breadcrumbs: [], breadcrumbs: [],
@ -64,8 +76,9 @@
/** /**
* Returns the full URL to the given directory * Returns the full URL to the given directory
* @param part crumb data as map *
* @param index crumb index * @param {Object.<String, String>} part crumb data as map
* @param {int} index crumb index
* @return full URL * @return full URL
*/ */
getCrumbUrl: function(part, index) { getCrumbUrl: function(part, index) {
@ -121,8 +134,9 @@
/** /**
* Makes a breadcrumb structure based on the given path * 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.<String, String>} map of {dir: path, name: displayName}
*/ */
_makeCrumbs: function(dir) { _makeCrumbs: function(dir) {
var crumbs = []; var crumbs = [];
@ -166,6 +180,8 @@
/** /**
* Show/hide breadcrumbs to fit the given width * Show/hide breadcrumbs to fit the given width
*
* @param {int} availableWidth available width
*/ */
setMaxWidth: function (availableWidth) { setMaxWidth: function (availableWidth) {
if (this.availableWidth !== availableWidth) { if (this.availableWidth !== availableWidth) {

View File

@ -49,7 +49,7 @@ function supportAjaxUploadWithProgress() {
/** /**
* keeps track of uploads in progress and implements callbacks for the conflicts dialog * keeps track of uploads in progress and implements callbacks for the conflicts dialog
* @type {OC.Upload} * @namespace
*/ */
OC.Upload = { OC.Upload = {
_uploads: [], _uploads: [],

View File

@ -13,11 +13,14 @@
/** /**
* Construct a new FileActions instance * Construct a new FileActions instance
* @constructs FileActions
* @memberof OCA.Files
*/ */
var FileActions = function() { var FileActions = function() {
this.initialize(); this.initialize();
} };
FileActions.prototype = { FileActions.prototype = {
/** @lends FileActions.prototype */
actions: {}, actions: {},
defaults: {}, defaults: {},
icons: {}, icons: {},
@ -31,9 +34,14 @@
/** /**
* List of handlers to be notified whenever a register() or * List of handlers to be notified whenever a register() or
* setDefault() was called. * setDefault() was called.
*
* @member {Function[]}
*/ */
_updateListeners: {}, _updateListeners: {},
/**
* @private
*/
initialize: function() { initialize: function() {
this.clear(); this.clear();
// abusing jquery for events until we get a real event lib // abusing jquery for events until we get a real event lib
@ -45,7 +53,7 @@
* Adds an event handler * Adds an event handler
* *
* @param {String} eventName event name * @param {String} eventName event name
* @param Function callback * @param {Function} callback
*/ */
on: function(eventName, callback) { on: function(eventName, callback) {
this.$el.on(eventName, callback); this.$el.on(eventName, callback);
@ -75,7 +83,7 @@
* Merges the actions from the given fileActions into * Merges the actions from the given fileActions into
* this instance. * this instance.
* *
* @param fileActions instance of OCA.Files.FileActions * @param {OCA.Files.FileActions} fileActions instance of OCA.Files.FileActions
*/ */
merge: function(fileActions) { merge: function(fileActions) {
var self = this; var self = this;
@ -113,8 +121,9 @@
* to the name given in action.name * to the name given in action.name
* @param {String} action.mime mime type * @param {String} action.mime mime type
* @param {int} action.permissions permissions * @param {int} action.permissions permissions
* @param {(Function|String)} action.icon icon * @param {(Function|String)} action.icon icon path to the icon or function
* @param {Function} action.actionHandler function that performs the action * that returns it
* @param {OCA.Files.FileActions~actionHandler} action.actionHandler action handler function
*/ */
registerAction: function (action) { registerAction: function (action) {
var mime = action.mime; var mime = action.mime;
@ -130,6 +139,9 @@
this.icons[name] = action.icon; this.icons[name] = action.icon;
this._notifyUpdateListeners('registerAction', {action: action}); this._notifyUpdateListeners('registerAction', {action: action});
}, },
/**
* Clears all registered file actions.
*/
clear: function() { clear: function() {
this.actions = {}; this.actions = {};
this.defaults = {}; this.defaults = {};
@ -137,6 +149,12 @@
this.currentFile = null; this.currentFile = null;
this._updateListeners = []; 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) { setDefault: function (mime, name) {
this.defaults[mime] = name; this.defaults[mime] = name;
this._notifyUpdateListeners('setDefault', {defaultAction: {mime: mime, name: name}}); this._notifyUpdateListeners('setDefault', {defaultAction: {mime: mime, name: name}});
@ -370,6 +388,18 @@
OCA.Files.FileActions = FileActions; 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 // global file actions to be used by all lists
OCA.Files.fileActions = new OCA.Files.FileActions(); OCA.Files.fileActions = new OCA.Files.FileActions();
OCA.Files.legacyFileActions = 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 // their actions on. Since legacy apps are very likely to break with other
// FileList views than the main one ("All files"), actions registered // FileList views than the main one ("All files"), actions registered
// through window.FileActions will be limited to the main file list. // through window.FileActions will be limited to the main file list.
// @deprecated use OCA.Files.FileActions instead
window.FileActions = OCA.Files.legacyFileActions; window.FileActions = OCA.Files.legacyFileActions;
window.FileActions.register = function (mime, name, permissions, icon, action, displayName) { window.FileActions.register = function (mime, name, permissions, icon, action, displayName) {
console.warn('FileActions.register() is deprecated, please use OCA.Files.fileActions.register() instead', arguments); console.warn('FileActions.register() is deprecated, please use OCA.Files.fileActions.register() instead', arguments);

View File

@ -10,13 +10,26 @@
(function() { (function() {
/** /**
* @class OCA.Files.FileList
* @classdesc
*
* The FileList class manages a file list view. * The FileList class manages a file list view.
* A file list view consists of a controls bar and * A file list view consists of a controls bar and
* a file list table. * 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) { var FileList = function($el, options) {
this.initialize($el, options); this.initialize($el, options);
}; };
/**
* @memberof OCA.Files
*/
FileList.prototype = { FileList.prototype = {
SORT_INDICATOR_ASC_CLASS: 'icon-triangle-n', SORT_INDICATOR_ASC_CLASS: 'icon-triangle-n',
SORT_INDICATOR_DESC_CLASS: 'icon-triangle-s', SORT_INDICATOR_DESC_CLASS: 'icon-triangle-s',
@ -41,15 +54,27 @@
*/ */
$fileList: null, $fileList: null,
/**
* @type OCA.Files.BreadCrumb
*/
breadcrumb: null, breadcrumb: null,
/** /**
* Instance of FileSummary * @type OCA.Files.FileSummary
*/ */
fileSummary: null, fileSummary: null,
/**
* Whether the file list was initialized already.
* @type boolean
*/
initialized: false, initialized: false,
// number of files per page, calculated dynamically /**
* Number of files per page
*
* @return {int} page size
*/
pageSize: function() { pageSize: function() {
return Math.ceil(this.$container.height() / 50); return Math.ceil(this.$container.height() / 50);
}, },
@ -57,37 +82,44 @@
/** /**
* Array of files in the current folder. * Array of files in the current folder.
* The entries are of file data. * The entries are of file data.
*
* @type Array.<Object>
*/ */
files: [], files: [],
/** /**
* File actions handler, defaults to OCA.Files.FileActions * File actions handler, defaults to OCA.Files.FileActions
* @type OCA.Files.FileActions
*/ */
fileActions: null, fileActions: null,
/** /**
* Map of file id to file data * Map of file id to file data
* @type Object.<int, Object>
*/ */
_selectedFiles: {}, _selectedFiles: {},
/** /**
* Summary of selected files. * Summary of selected files.
* Instance of FileSummary. * @type OCA.Files.FileSummary
*/ */
_selectionSummary: null, _selectionSummary: null,
/** /**
* Sort attribute * Sort attribute
* @type String
*/ */
_sort: 'name', _sort: 'name',
/** /**
* Sort direction: 'asc' or 'desc' * Sort direction: 'asc' or 'desc'
* @type String
*/ */
_sortDirection: 'asc', _sortDirection: 'asc',
/** /**
* Sort comparator function for the current sort * Sort comparator function for the current sort
* @type Function
*/ */
_sortComparator: null, _sortComparator: null,
@ -100,6 +132,7 @@
/** /**
* Current directory * Current directory
* @type String
*/ */
_currentDirectory: null, _currentDirectory: null,
@ -116,6 +149,7 @@
* @param options.dragOptions drag options, disabled by default * @param options.dragOptions drag options, disabled by default
* @param options.folderDropOptions folder drop 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 * @param options.scrollTo name of file to scroll to after the first load
* @private
*/ */
initialize: function($el, options) { initialize: function($el, options) {
var self = this; var self = this;
@ -192,6 +226,11 @@
this.fileActions.off('setDefault', this._onFileActionsUpdated); this.fileActions.off('setDefault', this._onFileActionsUpdated);
}, },
/**
* Initializes the file actions, set up listeners.
*
* @param {OCA.Files.FileActions} fileActions file actions
*/
_initFileActions: function(fileActions) { _initFileActions: function(fileActions) {
this.fileActions = fileActions; this.fileActions = fileActions;
if (!this.fileActions) { if (!this.fileActions) {
@ -588,8 +627,8 @@
}, },
/** /**
* Creates a new table row element using the given file data. * Creates a new table row element using the given file data.
* @param fileData map of file attributes * @param {OCA.Files.FileInfo} fileData file info attributes
* @param options map of attribute "loading" whether the entry is currently loading * @param options map of attributes
* @return new tr element (not appended to the table) * @return new tr element (not appended to the table)
*/ */
_createRow: function(fileData, options) { _createRow: function(fileData, options) {
@ -728,12 +767,14 @@
* Adds an entry to the files array and also into the DOM * Adds an entry to the files array and also into the DOM
* in a sorted manner. * in a sorted manner.
* *
* @param fileData map of file attributes * @param {OCA.Files.FileInfo} fileData map of file attributes
* @param options map of attributes: * @param {Object} [options] map of attributes
* @param options.updateSummary true to update the summary after adding (default), false otherwise * @param {boolean} [options.updateSummary] true to update the summary
* @param options.silent true to prevent firing events like "fileActionsReady" * after adding (default), false otherwise. Defaults to true.
* @param options.animate true to animate preview loading (defaults to true here) * @param {boolean} [options.silent] true to prevent firing events like "fileActionsReady",
* @param options.scrollTo true to automatically scroll to the file's location * 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) * @return new tr element (not appended to the table)
*/ */
add: function(fileData, options) { add: function(fileData, options) {
@ -799,11 +840,13 @@
* Creates a new row element based on the given attributes * Creates a new row element based on the given attributes
* and returns it. * and returns it.
* *
* @param fileData map of file attributes * @param {OCA.Files.FileInfo} fileData map of file attributes
* @param options map of attributes: * @param {Object} [options] map of attributes
* - "index" optional index at which to insert the element * @param {int} [options.index] index at which to insert the element
* - "updateSummary" true to update the summary after adding (default), false otherwise * @param {boolean} [options.updateSummary] true to update the summary
* - "animate" true to animate the preview rendering * 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) * @return new tr element (not appended to the table)
*/ */
_renderRow: function(fileData, options) { _renderRow: function(fileData, options) {
@ -870,6 +913,7 @@
}, },
/** /**
* Returns the current directory * Returns the current directory
* @method getCurrentDirectory
* @return current directory * @return current directory
*/ */
getCurrentDirectory: function(){ getCurrentDirectory: function(){
@ -1051,7 +1095,10 @@
/** /**
* Generates a preview URL based on the URL space. * 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 * @return preview URL
*/ */
generatePreviewUrl: function(urlSpec) { generatePreviewUrl: function(urlSpec) {
@ -1158,8 +1205,9 @@
/** /**
* Removes a file entry from the list * Removes a file entry from the list
* @param name name of the file to remove * @param name name of the file to remove
* @param options optional options as map: * @param {Object} [options] map of attributes
* "updateSummary": true to update the summary (default), false otherwise * @param {boolean} [options.updateSummary] true to update the summary
* after removing, false otherwise. Defaults to true.
* @return deleted element * @return deleted element
*/ */
remove: function(name, options){ remove: function(name, options){
@ -1201,6 +1249,8 @@
* Finds the index of the row before which the given * Finds the index of the row before which the given
* fileData should be inserted, considering the current * fileData should be inserted, considering the current
* sorting * sorting
*
* @param {OCA.Files.FileInfo} fileData file info
*/ */
_findInsertionIndex: function(fileData) { _findInsertionIndex: function(fileData) {
var index = 0; var index = 0;
@ -1515,7 +1565,7 @@
/** /**
* Shows the loading mask. * Shows the loading mask.
* *
* @see #hideMask * @see OCA.Files.FileList#hideMask
*/ */
showMask: function() { showMask: function() {
// in case one was shown before // in case one was shown before
@ -1536,7 +1586,7 @@
}, },
/** /**
* Hide the loading mask. * Hide the loading mask.
* @see #showMask * @see OCA.Files.FileList#showMask
*/ */
hideMask: function() { hideMask: function() {
this.$el.find('.mask').remove(); this.$el.find('.mask').remove();
@ -1961,15 +2011,17 @@
/** /**
* Sort comparators. * Sort comparators.
* @namespace OCA.Files.FileList.Comparators
* @private
*/ */
FileList.Comparators = { FileList.Comparators = {
/** /**
* Compares two file infos by name, making directories appear * Compares two file infos by name, making directories appear
* first. * first.
* *
* @param fileInfo1 file info * @param {OCA.Files.FileInfo} fileInfo1 file info
* @param fileInfo2 file info * @param {OCA.Files.FileInfo} fileInfo2 file info
* @return -1 if the first file must appear before the second one, * @return {int} -1 if the first file must appear before the second one,
* 0 if they are identify, 1 otherwise. * 0 if they are identify, 1 otherwise.
*/ */
name: function(fileInfo1, fileInfo2) { name: function(fileInfo1, fileInfo2) {
@ -1984,9 +2036,9 @@
/** /**
* Compares two file infos by size. * Compares two file infos by size.
* *
* @param fileInfo1 file info * @param {OCA.Files.FileInfo} fileInfo1 file info
* @param fileInfo2 file info * @param {OCA.Files.FileInfo} fileInfo2 file info
* @return -1 if the first file must appear before the second one, * @return {int} -1 if the first file must appear before the second one,
* 0 if they are identify, 1 otherwise. * 0 if they are identify, 1 otherwise.
*/ */
size: function(fileInfo1, fileInfo2) { size: function(fileInfo1, fileInfo2) {
@ -1995,9 +2047,9 @@
/** /**
* Compares two file infos by timestamp. * Compares two file infos by timestamp.
* *
* @param fileInfo1 file info * @param {OCA.Files.FileInfo} fileInfo1 file info
* @param fileInfo2 file info * @param {OCA.Files.FileInfo} fileInfo2 file info
* @return -1 if the first file must appear before the second one, * @return {int} -1 if the first file must appear before the second one,
* 0 if they are identify, 1 otherwise. * 0 if they are identify, 1 otherwise.
*/ */
mtime: function(fileInfo1, fileInfo2) { 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; OCA.Files.FileList = FileList;
})(); })();

View File

@ -195,7 +195,10 @@
/** /**
* Generates a preview URL based on the URL space. * 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 * @return preview URL
* @deprecated used OCA.Files.FileList.generatePreviewUrl instead * @deprecated used OCA.Files.FileList.generatePreviewUrl instead
*/ */

View File

@ -19,14 +19,15 @@
* *
*/ */
/* global OC, n, t */
(function() { (function() {
/** /**
* The FileSummary class encapsulates the file summary values and * The FileSummary class encapsulates the file summary values and
* the logic to render it in the given container * the logic to render it in the given container
*
* @constructs FileSummary
* @memberof OCA.Files
*
* @param $tr table row element * @param $tr table row element
* $param summary optional initial summary value
*/ */
var FileSummary = function($tr) { var FileSummary = function($tr) {
this.$el = $tr; this.$el = $tr;

View File

@ -13,10 +13,19 @@
(function() { (function() {
/**
* @class OCA.Files.Navigation
* @classdesc Navigation control for the files app sidebar.
*
* @param $el element containing the navigation
*/
var Navigation = function($el) { var Navigation = function($el) {
this.initialize($el); this.initialize($el);
}; };
/**
* @memberof OCA.Files
*/
Navigation.prototype = { Navigation.prototype = {
/** /**
@ -31,6 +40,8 @@
/** /**
* Initializes the navigation from the given container * Initializes the navigation from the given container
*
* @private
* @param $el element containing the navigation * @param $el element containing the navigation
*/ */
initialize: function($el) { initialize: function($el) {

View File

@ -8,7 +8,6 @@
* *
*/ */
/* global OC */
function Upload(fileSelector) { function Upload(fileSelector) {
if ($.support.xhrFileUpload) { if ($.support.xhrFileUpload) {
return new XHRUpload(fileSelector.target.files); return new XHRUpload(fileSelector.target.files);

View File

@ -5,6 +5,10 @@
* See the COPYING-README file. * See the COPYING-README file.
*/ */
/**
* @namespace
* @memberOf OC
*/
OC.Encryption={ OC.Encryption={
MIGRATION_OPEN:0, MIGRATION_OPEN:0,
MIGRATION_COMPLETED:1, MIGRATION_COMPLETED:1,

View File

@ -9,8 +9,14 @@
*/ */
if (!OCA.External) { if (!OCA.External) {
/**
* @namespace
*/
OCA.External = {}; OCA.External = {};
} }
/**
* @namespace
*/
OCA.External.App = { OCA.External.App = {
fileList: null, fileList: null,

View File

@ -10,15 +10,29 @@
(function() { (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) { var FileList = function($el, options) {
this.initialize($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', appName: 'External storage',
/**
* @private
*/
initialize: function($el, options) { initialize: function($el, options) {
OCA.Files.FileList.prototype.initialize.apply(this, arguments); OCA.Files.FileList.prototype.initialize.apply(this, arguments);
if (this.initialized) { if (this.initialized) {
@ -26,6 +40,9 @@
} }
}, },
/**
* @param {OCA.External.MountPointInfo} fileData
*/
_createRow: function(fileData) { _createRow: function(fileData) {
// TODO: hook earlier and render the whole row here // TODO: hook earlier and render the whole row here
var $tr = OCA.Files.FileList.prototype._createRow.apply(this, arguments); 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; OCA.External.FileList = FileList;
})(); })();

View File

@ -9,8 +9,14 @@
*/ */
if (!OCA.Sharing) { if (!OCA.Sharing) {
/**
* @namespace OCA.Sharing
*/
OCA.Sharing = {}; OCA.Sharing = {};
} }
/**
* @namespace
*/
OCA.Sharing.App = { OCA.Sharing.App = {
_inFileList: null, _inFileList: null,

View File

@ -16,9 +16,17 @@ if (!OCA.Sharing) {
if (!OCA.Files) { if (!OCA.Files) {
OCA.Files = {}; OCA.Files = {};
} }
/**
* @namespace
*/
OCA.Sharing.PublicApp = { OCA.Sharing.PublicApp = {
_initialized: false, _initialized: false,
/**
* Initializes the public share app.
*
* @param $el container
*/
initialize: function ($el) { initialize: function ($el) {
var self = this; var self = this;
var fileActions; var fileActions;

View File

@ -12,7 +12,19 @@
if (!OCA.Sharing) { if (!OCA.Sharing) {
OCA.Sharing = {}; OCA.Sharing = {};
} }
/**
* @namespace
*/
OCA.Sharing.Util = { 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) { initialize: function(fileActions) {
if (OCA.Files.FileList) { if (OCA.Files.FileList) {
var oldCreateRow = OCA.Files.FileList.prototype._createRow; var oldCreateRow = OCA.Files.FileList.prototype._createRow;
@ -160,9 +172,9 @@
* other ones will be shown as "+x" where "x" is the number of * other ones will be shown as "+x" where "x" is the number of
* remaining recipients. * remaining recipients.
* *
* @param recipients recipients array * @param {Array.<String>} recipients recipients array
* @param count optional total recipients count (in case the array was shortened) * @param {int} count optional total recipients count (in case the array was shortened)
* @return formatted recipients display text * @return {String} formatted recipients display text
*/ */
formatRecipients: function(recipients, count) { formatRecipients: function(recipients, count) {
var maxRecipients = 4; var maxRecipients = 4;

View File

@ -10,15 +10,25 @@
(function() { (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. * 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) { var FileList = function($el, options) {
this.initialize($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', appName: 'Shares',
/** /**
@ -27,9 +37,11 @@
*/ */
_sharedWithUser: false, _sharedWithUser: false,
_linksOnly: false, _linksOnly: false,
_clientSideSort: true, _clientSideSort: true,
/**
* @private
*/
initialize: function($el, options) { initialize: function($el, options) {
OCA.Files.FileList.prototype.initialize.apply(this, arguments); OCA.Files.FileList.prototype.initialize.apply(this, arguments);
if (this.initialized) { if (this.initialized) {
@ -138,8 +150,8 @@
/** /**
* Converts the OCS API share response data to a file info * Converts the OCS API share response data to a file info
* list * list
* @param OCS API share array * @param {Array} data OCS API share array
* @return array of file info maps * @return {Array.<OCA.Sharing.SharedFileInfo>} array of shared file info
*/ */
_makeFilesFromShares: function(data) { _makeFilesFromShares: function(data) {
/* jshint camelcase: false */ /* 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.<OCA.Sharing.ShareInfo>} 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.<String>} recipients name of the first 4 recipients
* (this is mostly for display purposes)
* @property {String} recipientsDisplayName display name
*/
OCA.Sharing.FileList = FileList; OCA.Sharing.FileList = FileList;
})(); })();

View File

@ -8,7 +8,13 @@
* *
*/ */
/**
* @namespace OCA.Trashbin
*/
OCA.Trashbin = {}; OCA.Trashbin = {};
/**
* @namespace OCA.Trashbin.App
*/
OCA.Trashbin.App = { OCA.Trashbin.App = {
_initialized: false, _initialized: false,

View File

@ -14,8 +14,8 @@
* Convert a file name in the format filename.d12345 to the real file name. * Convert a file name in the format filename.d12345 to the real file name.
* This will use basename. * This will use basename.
* The name will not be changed if it has no ".d12345" suffix. * The name will not be changed if it has no ".d12345" suffix.
* @param name file name * @param {String} name file name
* @return converted file name * @return {String} converted file name
*/ */
function getDeletedFileName(name) { function getDeletedFileName(name) {
name = OC.basename(name); name = OC.basename(name);
@ -26,13 +26,26 @@
return name; 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) { var FileList = function($el, options) {
this.initialize($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', id: 'trashbin',
appName: t('files_trashbin', 'Deleted files'), appName: t('files_trashbin', 'Deleted files'),
/**
* @private
*/
initialize: function() { initialize: function() {
var result = OCA.Files.FileList.prototype.initialize.apply(this, arguments); var result = OCA.Files.FileList.prototype.initialize.apply(this, arguments);
this.$el.find('.undelete').click('click', _.bind(this._onClickRestoreSelected, this)); this.$el.find('.undelete').click('click', _.bind(this._onClickRestoreSelected, this));

View File

@ -11,6 +11,8 @@
/* global scanFiles, escapeHTML, formatDate */ /* global scanFiles, escapeHTML, formatDate */
$(document).ready(function(){ $(document).ready(function(){
// TODO: namespace all this as OCA.FileVersions
if ($('#isPublic').val()){ if ($('#isPublic').val()){
// no versions actions in public mode // no versions actions in public mode
// beware of https://github.com/owncloud/core/issues/4545 // beware of https://github.com/owncloud/core/issues/4545

View File

@ -4,6 +4,9 @@
* See the COPYING-README file. * See the COPYING-README file.
*/ */
/**
* @namespace
*/
OC.AppConfig={ OC.AppConfig={
url:OC.filePath('core','ajax','appconfig.php'), url:OC.filePath('core','ajax','appconfig.php'),
getCall:function(action,data,callback){ getCall:function(action,data,callback){

View File

@ -34,6 +34,8 @@
* Create a new event source * Create a new event source
* @param {string} src * @param {string} src
* @param {object} [data] to be send as GET * @param {object} [data] to be send as GET
*
* @constructs OC.EventSource
*/ */
OC.EventSource=function(src,data){ OC.EventSource=function(src,data){
var dataStr=''; var dataStr='';
@ -92,6 +94,16 @@ OC.EventSource.prototype={
iframe:null, iframe:null,
listeners:{},//only for fallback listeners:{},//only for fallback
useFallBack:false, 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){ fallBackCallBack:function(type,data){
var i; var i;
// ignore messages that might appear after closing // ignore messages that might appear after closing
@ -111,6 +123,12 @@ OC.EventSource.prototype={
} }
}, },
lastLength:0,//for fallback 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){ listen:function(type,callback){
if(callback && callback.call){ if(callback && callback.call){
@ -134,6 +152,9 @@ OC.EventSource.prototype={
} }
} }
}, },
/**
* Closes this event source.
*/
close:function(){ close:function(){
this.closed = true; this.closed = true;
if (typeof this.source !== 'undefined') { if (typeof this.source !== 'undefined') {

View File

@ -5,6 +5,7 @@
* To the end of config/config.php to enable debug mode. * To the end of config/config.php to enable debug mode.
* The undefined checks fix the broken ie8 console * The undefined checks fix the broken ie8 console
*/ */
var oc_debug; var oc_debug;
var oc_webroot; var oc_webroot;
@ -57,6 +58,7 @@ function fileDownloadPath(dir, file) {
return OC.filePath('files', 'ajax', 'download.php')+'?files='+encodeURIComponent(file)+'&dir='+encodeURIComponent(dir); return OC.filePath('files', 'ajax', 'download.php')+'?files='+encodeURIComponent(file)+'&dir='+encodeURIComponent(dir);
} }
/** @namespace */
var OC={ var OC={
PERMISSION_CREATE:4, PERMISSION_CREATE:4,
PERMISSION_READ:1, 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) { basename: function(path) {
return path.replace(/\\/g,'/').replace( /.*\//, '' ); 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) { dirname: function(path) {
return path.replace(/\\/g,'/').replace(/\/[^\/]*$/, ''); return path.replace(/\\/g,'/').replace(/\/[^\/]*$/, '');
@ -277,12 +287,16 @@ var OC={
}); });
} }
}, 500), }, 500),
/**
* Dialog helper for jquery dialogs.
*
* @namespace OC.dialogs
*/
dialogs:OCdialogs, dialogs:OCdialogs,
/** /**
* Parses a URL query string into a JS map * Parses a URL query string into a JS map
* @param {string} queryString query string in the format param1=1234&param2=abcde&param3=xyz * @param {string} queryString query string in the format param1=1234&param2=abcde&param3=xyz
* @return map containing key/values matching the URL parameters * @return {Object.<string, string>} map containing key/values matching the URL parameters
*/ */
parseQueryString:function(queryString){ parseQueryString:function(queryString){
var parts, var parts,
@ -334,7 +348,7 @@ var OC={
/** /**
* Builds a URL query from a JS map. * Builds a URL query from a JS map.
* @param params parameter map * @param {Object.<string, string>} params map containing key/values matching the URL parameters
* @return {string} String containing a URL query (without question) mark * @return {string} String containing a URL query (without question) mark
*/ */
buildQueryString: function(params) { buildQueryString: function(params) {
@ -454,7 +468,7 @@ var OC={
* *
* This is makes it possible for unit tests to * This is makes it possible for unit tests to
* stub matchMedia (which doesn't work in PhantomJS) * stub matchMedia (which doesn't work in PhantomJS)
* @todo Write documentation * @private
*/ */
_matchMedia: function(media) { _matchMedia: function(media) {
if (window.matchMedia) { if (window.matchMedia) {
@ -464,6 +478,9 @@ var OC={
} }
}; };
/**
* @namespace OC.search
*/
OC.search.customResults={}; OC.search.customResults={};
OC.search.currentResult=-1; OC.search.currentResult=-1;
OC.search.lastQuery=''; OC.search.lastQuery='';
@ -531,6 +548,7 @@ OC.msg={
/** /**
* @todo Write documentation * @todo Write documentation
* @namespace
*/ */
OC.Notification={ OC.Notification={
queuedNotifications: [], 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={ OC.Breadcrumb={
container:null, container:null,
@ -721,6 +744,7 @@ OC.Breadcrumb={
if(typeof localStorage !=='undefined' && localStorage !== null){ if(typeof localStorage !=='undefined' && localStorage !== null){
/** /**
* User and instance aware localstorage * User and instance aware localstorage
* @namespace
*/ */
OC.localStorage={ OC.localStorage={
namespace:'oc_'+OC.currentUser+'_'+OC.webroot+'_', namespace:'oc_'+OC.currentUser+'_'+OC.webroot+'_',
@ -1164,6 +1188,7 @@ function relative_modified_date(timestamp) {
/** /**
* Utility functions * Utility functions
* @namespace
*/ */
OC.Util = { OC.Util = {
// TODO: remove original functions from global namespace // TODO: remove original functions from global namespace
@ -1314,6 +1339,8 @@ OC.Util = {
* Utility class for the history API, * Utility class for the history API,
* includes fallback to using the URL hash when * includes fallback to using the URL hash when
* the browser doesn't support the history API. * the browser doesn't support the history API.
*
* @namespace
*/ */
OC.Util.History = { OC.Util.History = {
_handlers: [], _handlers: [],
@ -1473,6 +1500,7 @@ OC.set=function(name, value) {
/** /**
* Namespace for apps * Namespace for apps
* @namespace OCA
*/ */
window.OCA = {}; window.OCA = {};

View File

@ -23,6 +23,7 @@
/** /**
* this class to ease the usage of jquery dialogs * this class to ease the usage of jquery dialogs
* @lends OC.dialogs
*/ */
var OCdialogs = { var OCdialogs = {
// dialog button types // dialog button types