New additions, tweaks, bug fixes, and complete documentation rewrite.

src/ajax.js

@@ -1,31 +1,31 @@
 /**
-* Namespace: yootil.ajax
-*	Useful methods for AJAX
-*/
+ * @class yootil.ajax
+ * @static
+ *	Useful methods for AJAX related stuff, mostly hooking into calls
+ */
 
 yootil.ajax = (function(){
 
 	return {
 
 		/**
-		* Method: bind
-		* 	Allows us add a global AJAX event to an element.
-		*
-		* Parameters:
-		* 	event - *string* The ajax event to bind (i.e "complete"), without "ajax" prefix.
-		* 	e - *object* The element to bind the event too.
-		* 	f - *function* This is the callback function that will get called.
-		* 	url - *string* / *boolean* The AJAX URL ProBoards calls to match against. If bool, match all.
-		* 	context - *object* The context ("this") of the callback function.
-		*
-		* Returns:
-		* 	*object* yootil
-		*
-		* Examples:
-		* 	yootil.ajax.bind("complete", $("form:first"), function(){ alert("AJAX completed"); });
-		*
-		* 	yootil.ajax.bind("complete", $("form:first"), function(){ alert("AJAX completed"); }, "/plugin/key/set/");
-		*/
+		 * Adds a global AJAX event to an element.
+		 *
+		 *     yootil.ajax.bind("complete", $("form:first"), function(){
+		 *     	alert("AJAX completed");
+		 *     });
+		 *
+		 *     yootil.ajax.bind("complete", $("form:first"), function(){
+		 *     	alert("AJAX completed");
+		 *     }, "/plugin/key/set/");
+		 *
+		 * @param {String} event The ajax event to bind (i.e "complete"), without "ajax" prefix.
+		 * @param {Object} e The element to bind the event too.
+		 * @param {Function} f This is the callback function that will get called.
+		 * @param {Mixed} url The AJAX URL ProBoards calls to match against. If it is a boolean, then it will match all.
+		 * @param {Object} [context] The context of the callback function.
+		 * @chainable
+		 */
 
 		bind: function(event, e, f, url, context){
 			var elem = $(e);
@@ -44,31 +44,22 @@ yootil.ajax = (function(){
 				}
 			}
 
-			return yootil;
+			return this;
 		},
 
 		/**
-		* Method: after_search
-		*	Because ProBoards uses AJAX for pagination, and on filtering (i.e members page),
-		*	we need to apply our DOM changes after the content on the page has been updated.
-		*	Currently there is no official callback, however the Live Query plugin is included,
-		*	but not recommended if you are after best performance.
-		*
-		* 	This is now a wrapper around ProBoards event.
-		*
-		*	Note:  Pages are cached, so you will need to check the DOM for your modified changes,
-		*	otherwise you will see it repeat without checking.
-		*
-		* Parameters:
-		*	func - *function* - The function that will be called after search.
-		*	context - *object* - Context of func
-		*
-		* Returns:
-		*	*object* Yootil
-		*/
+		 *	Because ProBoards uses AJAX for pagination and on filtering (i.e members page),
+		 *	we need to apply our DOM changes after the content on the page has been updated.
+		 *
+		 * @param {Function} func The function that will be called after search.
+		 * @param {Object} [context] Context of func.
+		 * @chainable
+		 */
 
 		after_search: function(func, context){
 			proboards.on("afterSearch", ((context)? $.proxy(func, context) : func));
+
+			return this;
 		}
 
 	};

src/bar.js

@@ -1,7 +1,8 @@
 /**
-* Namespace: yootil.bar
-*   Mimics the ProBoards Network bar, but on the left and for plugins.
-*/
+ * @class yootil.bar
+ * @static
+ * Mimics the ProBoards Network bar, but on the left and for plugins.
+ */
 
 yootil.bar = (function(){
 
@@ -33,17 +34,18 @@ yootil.bar = (function(){
 		},
 
 		/**
-		* Method: add
-		*	Use this to add an item to the Yootil Bar
-		*
-		* Parameters:
-		*	link - *string* URL for the item
-		*	img - *string* URL for the image
-		*	alt - *string* Alt / title for the image
-		*	id - *string* Pass in a unique ID if you wish to have the option to remove it later
-		*	func - *function* Pass function to be executed when clicked on
-		*	context - *mixed* Context of the function
-		*/
+		 * Add an item to the Yootil Bar.
+		 *
+		 *     yootil.bar.add("http://proboards.com", "http://example.com/someimage.png", "Hello World");
+		 *
+		 * @param {String} link URL for the item.
+		 * @param {String} img URL for the image.
+		 * @param {String} [alt] Alt / title for the image.
+		 * @param {String} [id] Pass in a unique ID if you wish to have the option to remove it later.
+		 * @param {Function} [func] Pass function to be executed when clicked on.
+		 * @param {Mixed} [context] Context of the function being passed.
+		 * @chainable
+		 */
 
 		add: function(link, img, alt, id, func, context){
 			var self = this;
@@ -70,18 +72,18 @@ yootil.bar = (function(){
 					}
 				}
 			});
+
+			return this;
 		},
 
 		/**
-		* Method: remove
-		*	Use this to remove an item to the Yootil Bar
-		*
-		* Parameters:
-		*	id - *string* The unique ID used when adding the item
-		*
-		* Returns:
-		*	*boolean*
-		*/
+		 * Remove an item to the Yootil Bar.
+		 *
+		 *     yootil.bar.remove("myitem");
+		 *
+		 * @param {String} id The unique ID used when adding the item.
+		 * @chainable
+		 */
 
 		remove: function(id){
 			if(id && id.toString().length && this._items["_" + id.toString()]){
@@ -93,30 +95,28 @@ yootil.bar = (function(){
 					this._bar.css("display", "none");
 				}
 			}
+
+			return this;
 		},
 
 		/**
-		* Method: total_items
-		*	Find out how many items are currently sitting in the bar
-		*
-		* Returns:
-		*	*integer"
-		*/
+		 * Find out how many items are currently sitting in the bar.
+		 *
+		 * @return {Number}
+		 */
 
 		total_items: function(){
 			return this._total_items;
 		},
 
 		/**
-		* Method: get
-		*	Use this to get the jQuery item (a tag)
-		*
-		* Parameters:
-		*	id - *string* The unique ID used when adding the item
-		*
-		* Returns:
-		*	*object* jQuery object is returned that wraps around the a tag
-		*/
+		 * Use this to get the item (jQuery wrapped)
+		 *
+		 *     yootil.get("myitem");
+		 *
+		 * @param {String} id The unique ID used when adding the item.
+		 * @return {Object} jQuery object is returned that wraps around the a tag.
+		 */
 
 		get: function(id){
 			if(id && id.toString().length && this._items["_" + id.toString()]){
@@ -125,15 +125,15 @@ yootil.bar = (function(){
 		},
 
 		/**
-		* Method: has
-		*	Use this to see if an item exists in the bar
-		*
-		* Parameters:
-		*	id - *string* The unique ID used when adding the item
-		*
-		* Returns:
-		*	*boolean*
-		*/
+		 * Use this to see if an item exists in the bar.
+		 *
+		 *     if(yootil.bar.has("myitem")){
+		 *     	console.log("item is in the yootil bar");
+		 *     }
+		 *
+		 * @param {String} id The unique ID used when adding the item.
+		 * @return {Boolean}
+		 */
 
 		has: function(id){
 			if(id && id.toString().length && this._items["_" + id.toString()]){
@@ -160,6 +160,16 @@ yootil.bar = (function(){
 			}
 		},
 
+		/**
+		 * Checks to see if the bar is enabled.
+		 *
+		 *     if(yootil.bar.is_enabled()){
+		 *     	console.log("Bar is enabled");
+		 *     }
+		 *
+		 * @return {Boolean}
+		 */
+
 		is_enabled: function(){
 			if(yootil.settings && yootil.settings.bar_enabled && yootil.settings.bar_enabled == 0){
 				return false;