update the doc strings

deluge/ui/web/js/deluge-all/Deluge.Events.js

@@ -20,34 +20,36 @@ Copyright:
 		51 Franklin Street, Fifth Floor
 		Boston, MA  02110-1301, USA.
 
-    In addition, as a special exception, the copyright holders give
+	In addition, as a special exception, the copyright holders give
-    permission to link the code of portions of this program with the OpenSSL
+	permission to link the code of portions of this program with the OpenSSL
-    library.
+	library.
-    You must obey the GNU General Public License in all respects for all of
+	You must obey the GNU General Public License in all respects for all of
-    the code used other than OpenSSL. If you modify file(s) with this
+	the code used other than OpenSSL. If you modify file(s) with this
-    exception, you may extend this exception to your version of the file(s),
+	exception, you may extend this exception to your version of the file(s),
-    but you are not obligated to do so. If you do not wish to do so, delete
+	but you are not obligated to do so. If you do not wish to do so, delete
-    this exception statement from your version. If you delete this exception
+	this exception statement from your version. If you delete this exception
-    statement from all source files in the program, then also delete it here.
+	statement from all source files in the program, then also delete it here.
 */
 
-/**
- * @namespace Deluge.Events
- * @class Deluge.Events
- * @name Deluge.Events
- * @description Class for holding global events that occur within the UI.
- */
-
 (function() {
-    Events = Ext.extend(Ext.util.Observable, {
+	/**
-        constructor: function() {
+	 * @class Deluge.Events
+	 * <p>Deluge.Events is a singleton that components of the UI can use to fire global events</p>
+	 * @singleton
+	 * Class for holding global events that occur within the UI.
+	 */
+	Events = Ext.extend(Ext.util.Observable, {
+		constructor: function() {
 			this.toRegister = [];
 			this.on('login', this.onLogin, this);
-            Events.superclass.constructor.call(this);
+			Events.superclass.constructor.call(this);
-        },
+		},
-        
+		
-        addListener: function(eventName, fn, scope, o) {
+		/**
-            this.addEvents(eventName);
+		 * Append an event handler to this object.
+		 */
+		addListener: function(eventName, fn, scope, o) {
+			this.addEvents(eventName);
 			if (/[A-Z]/.test(eventName.substring(0, 1))) {
 				if (!Deluge.Client) {
 					this.toRegister.push(eventName);
@@ -55,8 +57,8 @@ Copyright:
 					Deluge.Client.web.register_event_listener(eventName);
 				}
 			}
-            Events.superclass.addListener.call(this, eventName, fn, scope, o);
+			Events.superclass.addListener.call(this, eventName, fn, scope, o);
-        },
+		},
 	
 		poll: function() {
 			Deluge.Client.web.get_events({
@@ -65,6 +67,9 @@ Copyright:
 			});
 		},
 	
+		/**
+		 * Starts the EventsManager checking for events.
+		 */
 		start: function() {
 			Ext.each(this.toRegister, function(eventName) {
 				Deluge.Client.web.register_event_listener(eventName);
@@ -74,18 +79,23 @@ Copyright:
 			this.poll();
 		},
 	
+		/**
+		 * Stops the EventsManager checking for events.
+		 */
 		stop: function() {
 			if (this.running) {
 				clearInterval(this.running); 
 			}
 		},
 
+		// private
 		onLogin: function() {
 			this.start();
 			this.on('PluginEnabledEvent', this.onPluginEnabled, this);
 			this.on('PluginDisabledEvent', this.onPluginDisabled, this);
 		},
 	
+		// private
 		onPollSuccess: function(events) {
 			if (!events) return;
 			Ext.each(events, function(event) {
@@ -94,8 +104,18 @@ Copyright:
 				this.fireEvent.apply(this, args);
 			}, this);
 		}
-    });
+	});
-    Events.prototype.on = Events.prototype.addListener
+
-    Events.prototype.fire = Events.prototype.fireEvent
+	/**
-    Deluge.Events = new Events();
+	 * Appends an event handler to this object (shorthand for {@link #addListener})
+	 * @method 
+	 */
+	Events.prototype.on = Events.prototype.addListener
+
+	/**
+	 * Fires the specified event with the passed parameters (minus the event name).
+	 * @method 
+	 */
+	Events.prototype.fire = Events.prototype.fireEvent
+	Deluge.Events = new Events();
 })();

deluge/ui/web/js/deluge-all/Deluge.Formatters.js

@@ -32,16 +32,19 @@ Copyright:
 */
 
 /**
- * @description A collection of functions for string formatting values.
+ * A collection of functions for string formatting values.
- * @namespace Deluge.Formatters
+ * @class Deluge.Formatters
+ * @author Damien Churchill <damoxc@gmail.com>
+ * @version 1.3
+ * @singleton
  */
 Deluge.Formatters = {
 	/**
 	 * Formats a date string in the locale's date representation based on the
 	 * systems timezone.
 	 *
-	 * @param {number} timestamp time in seconds since the Epoch
+	 * @param {Number} timestamp time in seconds since the Epoch
-	 * @returns {string} a string in the locale's date representation or ""
+	 * @return {String} a string in the locale's date representation or ""
 	 * if seconds < 0
 	 */
 	date: function(timestamp) {
@@ -60,8 +63,8 @@ Deluge.Formatters = {
 	/**
 	 * Formats the bytes value into a string with KiB, MiB or GiB units.
 	 *
-	 * @param {number} bytes the filesize in bytes
+	 * @param {Number} bytes the filesize in bytes
-	 * @returns {string} formatted string with KiB, MiB or GiB units.
+	 * @return {String} formatted string with KiB, MiB or GiB units.
 	 */
 	size: function(bytes) {
 		if (!bytes) return '';
@@ -77,10 +80,10 @@ Deluge.Formatters = {
 	},
 	
 	/**
-	 * Formats a string to display a transfer speed utilizing {@link Deluge.Formatters.size}
+	 * Formats a string to display a transfer speed utilizing {@link #size}
 	 *
-	 * @param {number} bytes the filesize in bytes
+	 * @param {Number} bytes the filesize in bytes
-	 * @returns {string} formatted string with KiB, MiB or GiB units.
+	 * @return {String} formatted string with KiB, MiB or GiB units.
 	 */
 	speed: function(bits) {
 		return fsize(bits) + '/s'
@@ -89,8 +92,8 @@ Deluge.Formatters = {
 	/**
 	 * Formats a string to show time in a human readable form.
 	 *
-	 * @param {number} time the number of seconds
+	 * @param {Number} time the number of seconds
-	 * @returns {string} a formatted time string. will return '' if seconds == 0
+	 * @return {String} a formatted time string. will return '' if seconds == 0
 	 */
 	timeRemaining: function(time) {
 		if (time == 0) { return '∞' }
@@ -131,8 +134,8 @@ Deluge.Formatters = {
 	/**
 	 * Simply returns the value untouched, for when no formatting is required.
 	 *
-	 * @param value, the value to be displayed
+	 * @param {Mixed} value the value to be displayed
-	 * @returns the untouched value.
+	 * @return the untouched value.
 	 */
 	plain: function(value) {
 		return value;

deluge/ui/web/js/deluge-all/Deluge.Keys.js

@@ -33,11 +33,17 @@ Copyright:
 
 /**
  * @description The torrent status keys that are commonly used around the UI.
- * @namespace Deluge.Keys
+ * @class Deluge.Keys
+ * @singleton
  */
 Deluge.Keys = {
+
 	/**
-	 * @static
+	 * Keys that are used within the torrent grid.
+	 * <pre>['queue', 'name', 'total_size', 'state', 'progress', 'num_seeds',
+	 * 'total_seeds', 'num_peers', 'total_peers', 'download_payload_rate',
+	 * 'upload_payload_rate', 'eta', 'ratio', 'distributed_copies',
+	 * 'is_auto_managed', 'time_added', 'tracker_host']</pre>
 	 */
     Grid: [
         'queue', 'name', 'total_size', 'state', 'progress', 'num_seeds',
@@ -47,10 +53,12 @@ Deluge.Keys = {
     ],
     
     /**
-     * @description Keys used in the status tab of the statistics panel.
+     * Keys used in the status tab of the statistics panel.
-     * These get extended
+     * These get updated to include the keys in {@link #Grid}.
-     * by {@link Deluge.Keys.Grid}.
+	 * <pre>['total_done', 'total_payload_download', 'total_uploaded',
-	 * @static
+	 * 'total_payload_upload', 'next_announce', 'tracker_status', 'num_pieces',
+	 * 'piece_length', 'is_auto_managed', 'active_time', 'seeding_time',
+	 * 'seed_rank']</pre>
 	 */
     Status: [
         'total_done', 'total_payload_download', 'total_uploaded',
@@ -60,8 +68,7 @@ Deluge.Keys = {
     ],
     
     /**
-	 * @static
+     * Keys used in the files tab of the statistics panel.
-     * @description Keys used in the files tab of the statistics panel.
      * <pre>['files', 'file_progress', 'file_priorities']</pre>
 	 */
     Files: [
@@ -69,17 +76,15 @@ Deluge.Keys = {
     ],
     
     /**
-     * @description Keys used in the peers tab of the statistics panel.
+     * Keys used in the peers tab of the statistics panel.
      * <pre>['peers']</pre>
-	 * @static
 	 */
     Peers: [
         'peers'
     ],
     
     /**
-     * @description Keys used in the details tab of the statistics panel.
+     * Keys used in the details tab of the statistics panel.
-	 * @static
 	 */
     Details: [
         'name', 'save_path', 'total_size', 'num_files', 'tracker_status',
@@ -87,8 +92,7 @@ Deluge.Keys = {
     ],
     
     /**
-	 * @static
+	 * Keys used in the options tab of the statistics panel.
-	 * @description Keys used in the options tab of the statistics panel.
 	 * <pre>['max_download_speed', 'max_upload_speed', 'max_connections', 'max_upload_slots',
 	 *  'is_auto_managed', 'stop_at_ratio', 'stop_ratio', 'remove_at_ratio', 'private',
 	 *  'prioritize_first_last']</pre>

deluge/ui/web/js/deluge-all/Deluge.MultiOptionsManager.js

@@ -35,6 +35,7 @@ Copyright:
  * @description A class that can be used to manage options throughout the ui.
  * @namespace Deluge
  * @class Deluge.MultiOptionsManager
+ * @extends Deluge.OptionsManager
  */
 Deluge.MultiOptionsManager = Ext.extend(Deluge.OptionsManager, {
 
@@ -73,7 +74,7 @@ Deluge.MultiOptionsManager = Ext.extend(Deluge.OptionsManager, {
 	
 	/**
 	 * Get the value for an option
-	 * @param {String|Array} [option] A single option or an array of options to return.
+	 * @param {String/Array} option A single option or an array of options to return.
 	 * @returns {Object} the options value.
 	 */
 	get: function() {
@@ -97,7 +98,7 @@ Deluge.MultiOptionsManager = Ext.extend(Deluge.OptionsManager, {
 
 	/**
 	 * Get the default value for an option.
-	 * @param {String|Array} [option] A single option or an array of options to return.
+	 * @param {String} option A single option.
 	 * @returns {Object} the value of the option
 	 */
 	getDefault: function(option) {
@@ -182,7 +183,7 @@ Deluge.MultiOptionsManager = Ext.extend(Deluge.OptionsManager, {
 	/**
 	 * Update the value for the specified option and id.
 	 * @param {String} id
-	 * @param {String|Object} option or options to update
+	 * @param {String/Object} option or options to update
 	 * @param {Object} [value];
 	 */
 	update: function(option, value) {
@@ -212,9 +213,7 @@ Deluge.MultiOptionsManager = Ext.extend(Deluge.OptionsManager, {
 		}
 	},
 
-	/******************
+	// Event Handlers 
-	 * Event Handlers *
-	 ******************/
 	/**
 	 * Stops a form fields value from being blocked by the change functions
 	 * @param {Ext.form.Field} field
@@ -224,6 +223,13 @@ Deluge.MultiOptionsManager = Ext.extend(Deluge.OptionsManager, {
 		this.update(field._doption, field.getValue());
 	},
 
+	/**
+	 * Handles updating binds when an option's value is changed.
+	 * @param {String} id The current option id
+	 * @param {String} option The option that has changed.
+	 * @param {Mixed} newValue The new value
+	 * @private
+	 */
 	onChange: function(id, option, newValue, oldValue) {
 		// If we don't have a bind there's nothing to do.
 		if (Ext.isEmpty(this.binds[option])) return;

deluge/ui/web/js/deluge-all/Deluge.OptionsManager.js

@@ -43,9 +43,6 @@ Ext.namespace('Deluge');
  */
 Deluge.OptionsManager = Ext.extend(Ext.util.Observable, {
 	
-	/**
-	 * Create a new instance of the OptionsManager.
-	 */
 	constructor: function(config) {
 		config = config || {};
 		this.binds = {};
@@ -54,8 +51,25 @@ Deluge.OptionsManager = Ext.extend(Ext.util.Observable, {
 		this.focused = null;
 
 		this.addEvents({
+			/**
+			 * @event add
+			 * Fires when an option is added
+			 */
 			'add': true,
+
+			/**
+			 * @event changed
+			 * Fires when an option is changed
+			 * @param {String} option The changed option
+			 * @param {Mixed} value The options new value
+			 * @param {Mixed} oldValue The options old value
+			 */
 			'changed': true,
+
+			/**
+			 * @event reset
+			 * Fires when the options are reset
+			 */
 			'reset': true
 		});
 		this.on('changed', this.onChange, this);
@@ -205,7 +219,7 @@ Deluge.OptionsManager = Ext.extend(Ext.util.Observable, {
 
 	/**
 	 * Update the value for the specified option and id.
-	 * @param {String|Object} option or options to update
+	 * @param {String/Object} option or options to update
 	 * @param {Object} [value];
 	 */
 	update: function(option, value) {
@@ -233,9 +247,6 @@ Deluge.OptionsManager = Ext.extend(Ext.util.Observable, {
 		}
 	},
 
-	/******************
-	 * Event Handlers *
-	 ******************/
 	/**
 	 * Lets the option manager know when a field is blurred so if a value
 	 * so value changing operations can continue on that field.

deluge/ui/web/js/deluge-all/Deluge.Preferences.Proxy.js

@@ -121,9 +121,7 @@ Ext.deluge.preferences.ProxyField = Ext.extend(Ext.form.FieldSet, {
 		}
 	},
 
-	/**
+	// Set the values of the proxies
-	 * Set the values of the proxies
-	 */
 	setValue: function(value) {
 		this.setting = true;
 		this.type.setValue(value['type']);

deluge/ui/web/js/deluge-all/Deluge.Torrents.js

@@ -79,7 +79,7 @@ Copyright:
 	 * Ext.deluge.TorrentGrid Class
 	 *
 	 * @author Damien Churchill <damoxc@gmail.com>
-	 * @version 1.2
+	 * @version 1.3
 	 *
 	 * @class Ext.deluge.TorrentGrid
 	 * @extends Ext.grid.GridPanel