Commit 5ca869c3 authored by Vincent Petry's avatar Vincent Petry
Browse files

Merge pull request #9177 from owncloud/jsdocexperiment

Improved JS Docs + added build script for JS Docs
parents a069171c 0f3e6cb5
......@@ -89,6 +89,7 @@ nbproject
# nodejs
/build/lib/
/build/jsdocs/
/npm-debug.log
......
......@@ -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() {
......
......@@ -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 = $('<div class="breadcrumb"></div>');
......@@ -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.<String, String>} 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.<String, String>} 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) {
......
......@@ -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: [],
......
......@@ -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);
......
......@@ -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.<Object>
*/
files: [],
/**
* File actions handler, defaults to OCA.Files.FileActions
* @type OCA.Files.FileActions
*/
fileActions: null,
/**
* Map of file id to file data
* @type Object.<int, 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;
})();
......
......@@ -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
*/
......
......@@ -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;
......
......@@ -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) {
......
......@@ -8,7 +8,6 @@
*
*/
/* global OC */
function Upload(fileSelector) {
if ($.support.xhrFileUpload) {
return new XHRUpload(fileSelector.target.files);
......
......@@ -5,6 +5,10 @@
* See the COPYING-README file.
*/
/**
* @namespace
* @memberOf OC
*/
OC.Encryption={
MIGRATION_OPEN:0,
MIGRATION_COMPLETED:1,
......
......@@ -9,8 +9,14 @@
*/
if (!OCA.External) {
/**
* @namespace
*/
OCA.External = {};
}
/**
* @namespace
*/
OCA.External.App = {
fileList: null,
......