Merge pull request #9177 from owncloud/jsdocexperiment

Improved JS Docs + added build script for JS Docs

.gitignore

@@ -89,6 +89,7 @@ nbproject
 
 # nodejs
 /build/lib/
+/build/jsdocs/
 /npm-debug.log
 
 

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,13 +139,22 @@
 			this.icons[name] = action.icon;
 			this._notifyUpdateListeners('registerAction', {action: action});
 		},
+		/**
+		 * Clears all registered file actions.
+		 */
 		clear: function() {
 			this.actions = {};
 			this.defaults = {};
 			this.icons = {};
 			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);