From 0f3e6cb50af06bf3a64ea7f1abd360c53fa0bf8c Mon Sep 17 00:00:00 2001
From: Vincent Petry <pvince81@owncloud.com>
Date: Mon, 23 Jun 2014 23:56:10 +0200
Subject: Improved Javascript docs for JSDoc

Added namespaces so that JSDoc can find them.
Fixed a few warnings.
Improved some comments.
---
 apps/files_sharing/js/app.js            |  6 ++++
 apps/files_sharing/js/public.js         |  8 +++++
 apps/files_sharing/js/share.js          | 18 ++++++++++--
 apps/files_sharing/js/sharedfilelist.js | 52 +++++++++++++++++++++++++++++----
 4 files changed, 75 insertions(+), 9 deletions(-)

(limited to 'apps/files_sharing/js')

diff --git a/apps/files_sharing/js/app.js b/apps/files_sharing/js/app.js
index 1a3bfac5b97..1314304c567 100644
--- a/apps/files_sharing/js/app.js
+++ b/apps/files_sharing/js/app.js
@@ -9,8 +9,14 @@
  */
 
 if (!OCA.Sharing) {
+	/**
+	 * @namespace OCA.Sharing
+	 */
 	OCA.Sharing = {};
 }
+/**
+ * @namespace
+ */
 OCA.Sharing.App = {
 
 	_inFileList: null,
diff --git a/apps/files_sharing/js/public.js b/apps/files_sharing/js/public.js
index c4b5508692e..52679a7158d 100644
--- a/apps/files_sharing/js/public.js
+++ b/apps/files_sharing/js/public.js
@@ -16,9 +16,17 @@ if (!OCA.Sharing) {
 if (!OCA.Files) {
 	OCA.Files = {};
 }
+/**
+ * @namespace
+ */
 OCA.Sharing.PublicApp = {
 	_initialized: false,
 
+	/**
+	 * Initializes the public share app.
+	 *
+	 * @param $el container
+	 */
 	initialize: function ($el) {
 		var self = this;
 		var fileActions;
diff --git a/apps/files_sharing/js/share.js b/apps/files_sharing/js/share.js
index eccd21c9248..36ae878008d 100644
--- a/apps/files_sharing/js/share.js
+++ b/apps/files_sharing/js/share.js
@@ -12,7 +12,19 @@
 	if (!OCA.Sharing) {
 		OCA.Sharing = {};
 	}
+	/**
+	 * @namespace
+	 */
 	OCA.Sharing.Util = {
+		/**
+		 * Initialize the sharing app overrides of the default
+		 * file list.
+		 *
+		 * Registers the "Share" file action and adds additional
+		 * DOM attributes for the sharing file info.
+		 *
+		 * @param {OCA.Files.FileActions} fileActions file actions to extend
+		 */
 		initialize: function(fileActions) {
 			if (OCA.Files.FileList) {
 				var oldCreateRow = OCA.Files.FileList.prototype._createRow;
@@ -160,9 +172,9 @@
 		 * other ones will be shown as "+x" where "x" is the number of
 		 * remaining recipients.
 		 *
-		 * @param recipients recipients array
-		 * @param count optional total recipients count (in case the array was shortened)
-		 * @return formatted recipients display text
+		 * @param {Array.<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;
diff --git a/apps/files_sharing/js/sharedfilelist.js b/apps/files_sharing/js/sharedfilelist.js
index b99611f9bf0..5869d7f77f7 100644
--- a/apps/files_sharing/js/sharedfilelist.js
+++ b/apps/files_sharing/js/sharedfilelist.js
@@ -10,15 +10,25 @@
 (function() {
 
 	/**
-	 * Sharing file list
+	 * @class OCA.Sharing.FileList
+	 * @augments OCA.Files.FileList
 	 *
+	 * @classdesc Sharing file list.
 	 * Contains both "shared with others" and "shared with you" modes.
+	 *
+	 * @param $el container element with existing markup for the #controls
+	 * and a table
+	 * @param [options] map of options, see other parameters
+	 * @param {boolean} [options.sharedWithUser] true to return files shared with
+	 * the current user, false to return files that the user shared with others.
+	 * Defaults to false.
+	 * @param {boolean} [options.linksOnly] true to return only link shares
 	 */
 	var FileList = function($el, options) {
 		this.initialize($el, options);
 	};
-
-	FileList.prototype = _.extend({}, OCA.Files.FileList.prototype, {
+	FileList.prototype = _.extend({}, OCA.Files.FileList.prototype,
+		/** @lends OCA.Sharing.FileList.prototype */ {
 		appName: 'Shares',
 
 		/**
@@ -27,9 +37,11 @@
 		 */
 		_sharedWithUser: false,
 		_linksOnly: false,
-
 		_clientSideSort: true,
 
+		/**
+		 * @private
+		 */
 		initialize: function($el, options) {
 			OCA.Files.FileList.prototype.initialize.apply(this, arguments);
 			if (this.initialized) {
@@ -138,8 +150,8 @@
 		/**
 		 * Converts the OCS API share response data to a file info
 		 * list
-		 * @param OCS API share array
-		 * @return array of file info maps
+		 * @param {Array} data OCS API share array
+		 * @return {Array.<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;
 })();
-- 
cgit v1.2.3