Widget.disconnect is confusing / broken

[Ben Lowery]

The disconnect method of _Widget is really confusing. From the variable name and usage in the function, it appears to take an array of handles, but it only checks to see if one handle is present in this._connects before unhooking all of them. Also, it only removes the first handle found, not all in the passed array.

I couldn't find any tests for this method, so it's possible that it's just plain broken currently.

disconnect: function(/*Object*/ handles){
	// summary:
	//		Disconnects handle created by this.connect.
	//		Also removes handle from this widget's list of connects
	// tags:
	//		protected
	for(var i=0; i<this._connects.length; i++){
		if(this._connects[i]==handles){
			dojo.forEach(handles, dojo.disconnect);
			this._connects.splice(i, 1);
			return;
		}
	}
},

[Ben Lowery]

Just realized that this method is consistent with connect, as connect returns an array of handles, not just one.

So, nevermind. :)

[bill]

Right, I suppose I can make it clearer by modifying the API doc so that the return value of _Widget.connect() and the argument to _Widget.disconnect() is listed as _Widget.__connection, or some such name that indicates it's a black box representing a connect handle.

dojo.connect()'s return value and dojo.disconnect()'s parameter is listed as /*Handle*/ in the API comments; I should follow that lead.

[bill]

(In [17507]) Try to improve API documentation about return value of _Widget.connect() / parameter to _Widget.disconnect(). It should be considered a black box. Refs #9244 !strict.