Merge pull request #9177 from owncloud/jsdocexperiment

Improved JS Docs + added build script for JS Docs

4 files changed, 60 insertions, 7 deletions

diff --git a/core/js/config.js b/core/js/config.js
index 52d1c3aee25..b034b7e8cd3 100644
--- a/core/js/config.js
+++ b/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){
diff --git a/core/js/eventsource.js b/core/js/eventsource.js
index 46bd9f60bb5..6f23cebb685 100644
--- a/core/js/eventsource.js
+++ b/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') {
diff --git a/core/js/js.js b/core/js/js.js
index b1a61ddf502..39e382b544b 100644
--- a/core/js/js.js
+++ b/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 = {};
 
diff --git a/core/js/oc-dialogs.js b/core/js/oc-dialogs.js
index bd6fd2e5007..9e5afea1a6f 100644
--- a/core/js/oc-dialogs.js
+++ b/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