Refs #2538: Added documentation to most of the JS methods missing it.

git-svn-id: http://code.elgg.org/elgg/trunk@8717 36083f99-b078-4883-b0ff-0f9b5a30f544

9 files changed, 69 insertions, 12 deletions

diff --git a/js/classes/ElggPriorityList.js b/js/classes/ElggPriorityList.js
index 7b5d16473..831342f21 100644
--- a/js/classes/ElggPriorityList.js
+++ b/js/classes/ElggPriorityList.js
@@ -1,5 +1,6 @@
 /**
- *
+ * Priority lists allow you to create an indexed list that can be iterated through in a specific
+ * order.
  */
 elgg.ElggPriorityList = function() {
 	this.length = 0;
@@ -7,7 +8,12 @@ elgg.ElggPriorityList = function() {
 };
 
 /**
+ * Inserts an element into the priority list at the priority specified.
  *
+ * @param {Object} obj          The object to insert
+ * @param {Number} opt_priority An optional priority to insert at.
+ * 
+ * @return {Void}
  */
 elgg.ElggPriorityList.prototype.insert = function(obj, opt_priority) {
 	var priority = parseInt(opt_priority || 500, 10);
@@ -23,7 +29,13 @@ elgg.ElggPriorityList.prototype.insert = function(obj, opt_priority) {
 };
 
 /**
+ * Iterates through each element in order.
+ *
+* Unlike every, this ignores the return value of the callback.
  *
+ * @param {Function} callback The callback function to pass each element through. See
+ *                            Array.prototype.every() for details.
+ * @return {Object}
  */
 elgg.ElggPriorityList.prototype.forEach = function(callback) {
 	elgg.assertTypeOf('function', callback);
@@ -40,7 +52,13 @@ elgg.ElggPriorityList.prototype.forEach = function(callback) {
 };
 
 /**
+ * Iterates through each element in order.
+ *
+ * Unlike forEach, this returns the value of the callback and will break on false.
  *
+ * @param {Function} callback The callback function to pass each element through. See
+ *                            Array.prototype.every() for details.
+ * @return {Object}
  */
 elgg.ElggPriorityList.prototype.every = function(callback) {
 	elgg.assertTypeOf('function', callback);
@@ -55,7 +73,10 @@ elgg.ElggPriorityList.prototype.every = function(callback) {
 };
 
 /**
+ * Removes an element from the priority list
  *
+ * @param {Object} obj The object to remove.
+ * @return {Void}
  */
 elgg.ElggPriorityList.prototype.remove = function(obj) {
 	this.priorities_.forEach(function(elems) {
diff --git a/js/lib/elgglib.js b/js/lib/elgglib.js
index 4137c4a7a..f6d5f51ce 100644
--- a/js/lib/elgglib.js
+++ b/js/lib/elgglib.js
@@ -238,7 +238,7 @@ elgg.inherit = function(Child, Parent) {
  * If the url is already absolute or protocol-relative, no change is made.
  *
  * elgg.normalize_url('');                   // 'http://my.site.com/'
- * elgg.normalize_url('dashboard');       // 'http://my.site.com/dashboard'
+ * elgg.normalize_url('dashboard');          // 'http://my.site.com/dashboard'
  * elgg.normalize_url('http://google.com/'); // no change
  * elgg.normalize_url('//google.com/');      // no change
  *
@@ -326,7 +326,7 @@ elgg.system_messages = function(msgs, delay, type) {
 
 /**
  * Wrapper function for system_messages. Specifies "messages" as the type of message
- * @param {String} msg The message to display
+ * @param {String} msgs  The message to display
  * @param {Number} delay How long to display the message (milliseconds)
  */
 elgg.system_message = function(msgs, delay) {
@@ -335,8 +335,8 @@ elgg.system_message = function(msgs, delay) {
 
 /**
  * Wrapper function for system_messages.  Specifies "errors" as the type of message
- * @param {String} error The error message to display
- * @param {Number} delay How long to dispaly the error message (milliseconds)
+ * @param {String} errors The error message to display
+ * @param {Number} delay  How long to dispaly the error message (milliseconds)
  */
 elgg.register_error = function(errors, delay) {
 	elgg.system_messages(errors, delay, "error");
diff --git a/js/lib/hooks.js b/js/lib/hooks.js
index 9c86a1fec..aab129d6e 100644
--- a/js/lib/hooks.js
+++ b/js/lib/hooks.js
@@ -70,8 +70,6 @@ elgg.trigger_hook = function(name, type, params, value) {
 		returnValue = value,
 		callHookHandler = function(handler) {
 			tempReturnValue = handler(name, type, params, value);
-			// always continue through all the handlers
-			return true;
 		};
 
 	elgg.provide(name + '.' + type, hooks);
@@ -85,7 +83,7 @@ elgg.trigger_hook = function(name, type, params, value) {
 		hooks['all']['all']
 	].every(function(handlers) {
 		if (handlers instanceof elgg.ElggPriorityList) {
-			handlers.every(callHookHandler);
+			handlers.forEach(callHookHandler);
 		}
 		return true;
 	});
diff --git a/js/lib/languages.js b/js/lib/languages.js
index 79768c471..06af1ca7f 100644
--- a/js/lib/languages.js
+++ b/js/lib/languages.js
@@ -25,6 +25,7 @@ elgg.add_translation = function(lang, translations) {
  */
 elgg.reload_all_translations = function(language) {
 	var lang = language || elgg.get_language();
+	// This...................vvvvv is a double encoded question mark (? -> %2f -> %252f)
 	elgg.getJSON('js/languages%252f' + lang + '.js', {
 		data: {
 			'viewtype': 'default',
diff --git a/js/lib/prototypes.js b/js/lib/prototypes.js
index 0f0014818..cb6184097 100644
--- a/js/lib/prototypes.js
+++ b/js/lib/prototypes.js
@@ -1,5 +1,14 @@
 /**
+ * Interates through each element of an array and calls a callback function.
+ * The callback should accept the following arguments:
+ *	element - The current element
+ *	index	- The current index
  *
+ * This is different to Array.forEach in that if the callback returns false, the loop returns
+ * immediately without processing the remaining elements.
+ *
+ *	@param {Function} callback
+ *	@return {Bool}
  */
 if (!Array.prototype.every) {
 	Array.prototype.every = function(callback) {
@@ -16,7 +25,16 @@ if (!Array.prototype.every) {
 }
 
 /**
+ * Interates through each element of an array and calls callback a function.
+ * The callback should accept the following arguments:
+ *	element - The current element
+ *	index	- The current index
+ *
+ * This is different to Array.every in that the callback's return value is ignored and every
+ * element of the array will be parsed.
  *
+ *	@param {Function} callback
+ *	@return {Void}
  */
 if (!Array.prototype.forEach) {
 	Array.prototype.forEach = function(callback) {
@@ -31,7 +49,11 @@ if (!Array.prototype.forEach) {
 }
 
 /**
+ * Left trim
  *
+ * Removes a character from the left side of a string.
+ * @param {String} str The character to remove
+ * @return {String}
  */
 if (!String.prototype.ltrim) {
 	String.prototype.ltrim = function(str) {
diff --git a/js/lib/security.js b/js/lib/security.js
index d449d8887..f88c6165d 100644
--- a/js/lib/security.js
+++ b/js/lib/security.js
@@ -5,6 +5,12 @@ elgg.provide('elgg.security');
 
 elgg.security.token = {};
 
+/**
+ * Sets the currently active security token and updates all forms and links on the current page.
+ *
+ * @param {Object} json The json representation of a token containing __elgg_ts and __elgg_token
+ * @return {Void}
+ */
 elgg.security.setToken = function(json) {
 	//update the convenience object
 	elgg.security.token = json;
@@ -22,7 +28,7 @@ elgg.security.setToken = function(json) {
 };
 
 /**
- * Security tokens time out, so lets refresh those every so often
+ * Security tokens time out, so lets refresh those every so often.
  * 
  * @todo handle error and bad return data
  */
@@ -70,6 +76,7 @@ elgg.security.addToken = function(data) {
 
 elgg.security.init = function() {
 	//refresh security token every 5 minutes
+	//this is set in the js/elgg PHP view.
 	setInterval(elgg.security.refreshToken, elgg.security.interval);
 };
 
diff --git a/js/lib/session.js b/js/lib/session.js
index a1454aa50..fa3d60aa9 100644
--- a/js/lib/session.js
+++ b/js/lib/session.js
@@ -1,5 +1,5 @@
 /**
- * @todo comment
+ * Provides session methods.
  */
 elgg.provide('elgg.session');
 
@@ -8,6 +8,7 @@ elgg.provide('elgg.session');
  * @param {string} name
  * @param {string} value
  * @param {Object} options
+ * 
  *  {number|Date} options[expires]
  * 	{string} options[path]
  * 	{string} options[domain]
@@ -81,6 +82,8 @@ elgg.session.cookie = function (name, value, options) {
 };
 
 /**
+ * Returns the object of the user logged in.
+ *
  * @return {ElggUser} The logged in user
  */
 elgg.get_logged_in_user_entity = function() {
@@ -88,6 +91,8 @@ elgg.get_logged_in_user_entity = function() {
 };
 
 /**
+ * Returns the GUID of the logged in user or 0.
+ *
  * @return {number} The GUID of the logged in user
  */
 elgg.get_logged_in_user_guid = function() {
@@ -96,6 +101,8 @@ elgg.get_logged_in_user_guid = function() {
 };
 
 /**
+ * Returns if a user is logged in.
+ *
  * @return {boolean} Whether there is a user logged in
  */
 elgg.is_logged_in = function() {
@@ -103,6 +110,8 @@ elgg.is_logged_in = function() {
 };
 
 /**
+ * Returns if the currently logged in user is an admin.
+ *
  * @return {boolean} Whether there is an admin logged in
  */
 elgg.is_admin_logged_in = function() {
diff --git a/js/lib/ui.js b/js/lib/ui.js
index 22475df93..0600eb0cb 100644
--- a/js/lib/ui.js
+++ b/js/lib/ui.js
@@ -201,5 +201,4 @@ elgg.ui.likesPopupHandler = function(hook, type, params, options) {
 };
 
 elgg.register_hook_handler('init', 'system', elgg.ui.init);
-//elgg.register_hook_handler('popup', 'ui', elgg.ui.likesPopupHandler);
 elgg.register_hook_handler('getOptions', 'ui.popup', elgg.ui.likesPopupHandler);
\ No newline at end of file
diff --git a/js/lib/userpicker.js b/js/lib/userpicker.js
index b551ea830..475af150f 100644
--- a/js/lib/userpicker.js
+++ b/js/lib/userpicker.js
@@ -2,7 +2,7 @@ elgg.provide('elgg.userpicker');
 
 elgg.userpicker.init = function() {
 	// binding autocomplete.
-	// doing this as an each so we can past this to functions.
+	// doing this as an each so we can pass this to functions.
 	$('.elgg-input-user-picker').each(function() {
 		
 		var _this = this;