Added DOC blocks to all new JS code

ckan/public/base/javascript/client.js

@@ -25,6 +25,18 @@
       return path;
     },
 
+    /* Simple helper function for both GET's and POST's to the ckan API
+     * 
+     * type - GET or POST
+     * path - The API endpoint
+     * data - Any data you need passing to the endpoint
+     * fn - The callback function that you want the result data passed to
+     *
+     * Examples
+     *
+     *    client.call('GET', 'user_show', { id: 'some-long-id' }, function(json) { console.log(json) })
+     *
+     */
     call: function(type, path, data, fn) {
       var url = this.url('/api/action/' + path);
       var options = {

ckan/public/base/javascript/module.js

@@ -268,6 +268,16 @@ this.ckan = this.ckan || {};
     return module;
   };
 
+  /* Initializes an individual dom modules element
+   *
+   * element = DOM node you want to initialize (not jQuery collection)
+   * 
+   * Examples
+   *
+   *    ckan.module.initializeElement(jQuery('[data-module="foo"]')[0])
+   *
+   * Returns nothing
+   */
   module.initializeElement = function(element) {
     var registry = module.registry;
     var names = jQuery.trim(element.getAttribute(MODULE_PREFIX)).split(' ');

ckan/public/base/javascript/modules/follow.js

@@ -1,5 +1,19 @@
+/* Follow buttons
+ * Handles calling the API to follow the current user
+ *
+ * action - This being the action that the button should perform. Currently: "follow" or "unfollow"
+ * type - The being the type of object the user is trying to support. Currently: "user" or "group"
+ * id - id of the objec the user is trying to follow
+ * loading - State management helper
+ *
+ * Examples
+ *
+ *   <a data-module="follow" data-module-action="follow" data-module-type="user" data-module-id="{user_id}">Follow User</a>
+ *
+ */
 this.ckan.module('follow', function($, _) {
 	return {
+		/* options object can be extended using data-module-* attributes */
 		options : {
 			action: null,
 			type: null,
@@ -10,27 +24,45 @@ this.ckan.module('follow', function($, _) {
 				unfollow: _('Unfollow')
 			}
 		},
+
+		/* Initialises the module setting up elements and event listeners.
+		 *
+		 * Returns nothing.
+		 */
 		initialize: function () {
 			$.proxyAll(this, /_on/);
 			this.el.on('click', this._onClick);
 		},
-		_onClick: function(e) {
+
+		/* Handles the clicking of the follow button
+		 *
+		 * event - An event object.
+		 *
+		 * Returns nothing.
+		 */
+		_onClick: function(event) {
 			var options = this.options;
-			e.preventDefault();
 			if (
 				options.action
 				&& options.type
 				&& options.id
 				&& !options.loading
 			) {
+				event.preventDefault();
 				var client = this.sandbox.client;
 				var path = options.action + '_' + options.type;
 				options.loading = true;
 				this.el.addClass('disabled');
 				client.call('POST', path, { id : options.id }, this._onClickLoaded);
 			}
-			return false;
 		},
+
+		/* Fired after the call to the API to either follow or unfollow
+		 *
+		 * json - The return json from the follow / unfollow API call
+		 *
+		 * Returns nothing.
+		 */
 		_onClickLoaded: function(json) {
 			var options = this.options;
 			options.loading = false;

ckan/public/base/javascript/modules/user-context.js

@@ -1,6 +1,27 @@
+/* User context hover/popovers
+ * These appear when someone hovers over a avatar in a activity stream to
+ * give the user more context into that particular user. It also allows for people to
+ * follow and unfollow quickly from within the popover
+ *
+ * id - The user_id of user
+ * url - The URL of the profile for that user
+ * loading - Loading sat helper
+ * authed - Is the current user authed ... if so what's their user_id
+ * template - Simple string-replace template for content of popover
+ *
+ * Examples
+ *
+ *   <a data-module="user-context" data-module-id="{user_id}">A user</a>
+ *
+ */
+
+// Global dictionary store for users
 window.user_context_dict = {};
+
 this.ckan.module('user-context', function($, _) {
 	return {
+
+		/* options object can be extended using data-module-* attributes */
 		options : {
 			id: null,
 			loading: false,
@@ -13,6 +34,11 @@ this.ckan.module('user-context', function($, _) {
 				loading: _('Loading...')
 			}
 		},
+
+		/* Initialises the module setting up elements and event listeners.
+		 *
+		 * Returns nothing.
+		 */
 		initialize: function () {
 			if (
 				this.options.id != true
@@ -30,8 +56,23 @@ this.ckan.module('user-context', function($, _) {
 				this.el.on('mouseover', this._onMouseOver);	
 			}
 		},
+
+		/* Handles the showing of the popover on hover (also hides other active popovers)
+		 *
+		 * Returns nothing.
+		 */
+		_onMouseOver: function() {
+			$('[data-module="user-context"]').popover('hide');
+			this.el.popover('show');
+			this.getUserData();
+		},
+
+		/* Get's the user data from the ckan api
+		 *
+		 * Returns nothing.
+		 */
 		getUserData: function() {
-			if (!this.loading) {
+			if (!this.options.loading) {
 				var id = this.options.id;
 				if (typeof window.user_context_dict[id] == 'undefined') {
 					var client = this.sandbox.client;
@@ -42,11 +83,11 @@ this.ckan.module('user-context', function($, _) {
 				}
 			}
 		},
-		_onMouseOver: function(e) {
-			$('[data-module="user-context"]').popover('hide');
-			this.el.popover('show');
-			this.getUserData();
-		},
+
+		/* Callback from getting the user_show from the ckan api
+		 *
+		 * Returns nothing.
+		 */
 		_onHandleUserData: function(json) {
 			this.loading = false;
 			if (json.success) {
@@ -73,7 +114,7 @@ this.ckan.module('user-context', function($, _) {
 						.replace('{{ buttons }}', this._getButtons(user));
 					$('.popover-title', tip).html('<a href="javascript:;" class="popover-close">&times;</a>' + user.display_name);
 					$('.popover-content', tip).html(template);
-					$('.popover-close', tip).on('click', this._onHandlePopoverClose);
+					$('.popover-close', tip).on('click', this._onClickPopoverClose);
 					var follow_check = $('[data-module="follow"]', tip);
 					if (follow_check.length > 0) {
 						ckan.module.initializeElement(follow_check[0]);
@@ -82,19 +123,46 @@ this.ckan.module('user-context', function($, _) {
 				window.user_context_dict[this.options.id] = json;
 			}
 		},
-		_onHandlePopoverClose: function() {
+
+		/* Handles closing the currently open popover
+		 *
+		 * Returns nothing.
+		 */
+		_onClickPopoverClose: function() {
 			this.el.popover('hide');
 		},
+
+		/* Callback from getting the number of followers for given user
+		 *
+		 * json - user dict
+		 *
+		 * Returns nothing.
+		 */
 		_onHandleUserFollowersData: function(json) {
 			var data = window.user_context_dict[this.options.id];
 			data.result.number_of_followers = json.result;
 			this._onHandleUserData(data);
 		},
+
+		/* Callback from getting whether the currently authed user is following
+		 * said user
+		 * 
+		 * json - user dict
+		 *
+		 * Returns nothing.
+		 */
 		_onHandleAmFollowingData: function(json) {
 			var data = window.user_context_dict[this.options.id];
 			data.result.am_following_user = json.result;
 			this._onHandleUserData(data);
 		},
+
+		/* Returns the HTML associated to the button controls
+		 *
+		 * user = user dict
+		 *
+		 * Returns nothing.
+		 */
 		_getButtons: function(user) {
 			var html = '';
 			if (