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

@@ -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() {

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 = $('<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) {

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: [],

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);

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.<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;
 })();
 

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
 		 */

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;

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) {

apps/files/js/upload.js

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

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,

apps/files_external/js/app.js

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

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;
 })();

apps/files_sharing/js/app.js

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

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;

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.<String>} 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;

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.<OCA.Sharing.SharedFileInfo>} 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.<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;
 })();

apps/files_trashbin/js/app.js

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

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));

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

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){

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') {

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&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){
 		var parts,
@@ -334,7 +348,7 @@ var OC={
 
 	/**
 	 * 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
 	 */
 	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 = {};
 

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