Fix the comment of newWithValues: and add a test

I've added a test to ensure that `BlockClosure#newWithValues:` will not
silently consume errrors if the argument list is wrong. I've also
updated the comment of `newWithValues:` to try and fit with Amber's
comment guidelines.

js/Kernel-Methods.deploy.js

@@ -130,11 +130,11 @@ fn: function (aCollection){
 var self=this;
 return smalltalk.withContext(function($ctx1) { 
 
-var duck = function() {};
-duck.prototype = self.prototype;
-var duckInstance = new duck;
-var result = self.apply(duckInstance, aCollection);
-return typeof result === "object" ? result : duckInstance;;
+var blankObject = function() {};
+blankObject.prototype = self.prototype;
+var newObject = new blankObject;
+var result = self.apply(newObject, aCollection);
+return typeof result === "object" ? result : newObject;;
 return self}, function($ctx1) {$ctx1.fill(self,"newWithValues:",{aCollection:aCollection},smalltalk.BlockClosure)})},
 messageSends: []}),
 smalltalk.BlockClosure);

js/Kernel-Methods.js

@@ -182,14 +182,14 @@ fn: function (aCollection){
 var self=this;
 return smalltalk.withContext(function($ctx1) { 
 
-var duck = function() {};
-duck.prototype = self.prototype;
-var duckInstance = new duck;
-var result = self.apply(duckInstance, aCollection);
-return typeof result === "object" ? result : duckInstance;;
+var blankObject = function() {};
+blankObject.prototype = self.prototype;
+var newObject = new blankObject;
+var result = self.apply(newObject, aCollection);
+return typeof result === "object" ? result : newObject;;
 return self}, function($ctx1) {$ctx1.fill(self,"newWithValues:",{aCollection:aCollection},smalltalk.BlockClosure)})},
 args: ["aCollection"],
-source: "newWithValues: aCollection\x0a\x22I'll apply a variable number of arguments to a function, and return the object created.\x0a\x0aNote: This is apparently just what Coffeescript does; I know because I was 'inspired' by http://stackoverflow.com/a/6069331.\x0a\x0aHere's a general breakdown of what's going on:\x0a1) Create a new, blank function object.\x0a2) Set it's prototype to 'my' prototype. Remember, we are in a BlockClosure, and presumably this BlockClosure is wrapping a JS function, and also presumably this function is used as a constructor.\x0a3) Instantiate a new version of the function object we just created. This forces the interpreter to set the internal [[prototype]] property to what was set on the function before. This has to be done, as we have no access to the [[prototype]] property externally.\x0a4) Apply 'myself' to the object I just instantiated.\x22\x0a<\x0avar duck = function() {};\x0aduck.prototype = self.prototype;\x0avar duckInstance = new duck;\x0avar result = self.apply(duckInstance, aCollection);\x0areturn typeof result === \x22object\x22 ? result : duckInstance;\x0a>",
+source: "newWithValues: aCollection\x0a\x22Answer an object that's been created in JS via `new` and had `self` applied to it.\x0aThis algorithm was inspired by http://stackoverflow.com/a/6069331.\x0a\x0aHere's a general breakdown of what's going on:\x0a1) Create a new, blank function object.\x0a2) Set it's prototype to `self`'s prototype. Remember, we're in a BlockClosure, and presumably this BlockClosure is wrapping a JS function, and also presumably this function is used as a constructor.\x0a3) Instantiate a new version of the function object just created. This forces the interpreter to set the internal [[prototype]] property to what was set on the function before. This has to be done, as we have no access to the [[prototype]] property externally.\x0a4) Apply `self` to the object I just instantiated.\x22\x0a<\x0avar blankObject = function() {};\x0ablankObject.prototype = self.prototype;\x0avar newObject = new blankObject;\x0avar result = self.apply(newObject, aCollection);\x0areturn typeof result === \x22object\x22 ? result : newObject;\x0a>",
 messageSends: [],
 referencedClasses: []
 }),

js/Kernel-Tests.deploy.js

@@ -146,16 +146,17 @@ fn: function (){
 var self=this;
 return smalltalk.withContext(function($ctx1) { 
 
-function theTestPrototype() {
-	this.name = "theTestPrototype";
-}
+function theTestPrototype() {this.name = "theTestPrototype";}
 function theTestConstructor(arg1, arg2, arg3) {}
 theTestConstructor.prototype = new theTestPrototype;
 
 var theWrappedConstructor = _st(theTestConstructor);
 var theResult = theWrappedConstructor._newWithValues_([1, 2, 3]);
+self._assert_equals_(Object.getPrototypeOf(theResult).name, 'theTestPrototype');
 
-self._assert_equals_(Object.getPrototypeOf(theResult).name, 'theTestPrototype');;
+"newWithValues: cannot help if the argument list is wrong, and should warn that a mistake was made."
+function constructionShouldFail() {var anotherResult = theWrappedConstructor._newWithValues_('This is so wrong');}
+self._should_raise_(_st(constructionShouldFail), smalltalk.Error);;
 return self}, function($ctx1) {$ctx1.fill(self,"testNewWithValues",{},smalltalk.BlockClosureTest)})},
 messageSends: []}),
 smalltalk.BlockClosureTest);

js/Kernel-Tests.js

@@ -182,19 +182,20 @@ fn: function (){
 var self=this;
 return smalltalk.withContext(function($ctx1) { 
 
-function theTestPrototype() {
-	this.name = "theTestPrototype";
-}
+function theTestPrototype() {this.name = "theTestPrototype";}
 function theTestConstructor(arg1, arg2, arg3) {}
 theTestConstructor.prototype = new theTestPrototype;
 
 var theWrappedConstructor = _st(theTestConstructor);
 var theResult = theWrappedConstructor._newWithValues_([1, 2, 3]);
+self._assert_equals_(Object.getPrototypeOf(theResult).name, 'theTestPrototype');
 
-self._assert_equals_(Object.getPrototypeOf(theResult).name, 'theTestPrototype');;
+"newWithValues: cannot help if the argument list is wrong, and should warn that a mistake was made."
+function constructionShouldFail() {var anotherResult = theWrappedConstructor._newWithValues_('This is so wrong');}
+self._should_raise_(_st(constructionShouldFail), smalltalk.Error);;
 return self}, function($ctx1) {$ctx1.fill(self,"testNewWithValues",{},smalltalk.BlockClosureTest)})},
 args: [],
-source: "testNewWithValues\x0a<\x0afunction theTestPrototype() {\x0a\x09this.name = \x22theTestPrototype\x22;\x0a}\x0afunction theTestConstructor(arg1, arg2, arg3) {}\x0atheTestConstructor.prototype = new theTestPrototype;\x0a\x0avar theWrappedConstructor = _st(theTestConstructor);\x0avar theResult = theWrappedConstructor._newWithValues_([1, 2, 3]);\x0a\x0aself._assert_equals_(Object.getPrototypeOf(theResult).name, 'theTestPrototype');\x0a>",
+source: "testNewWithValues\x0a<\x0afunction theTestPrototype() {this.name = \x22theTestPrototype\x22;}\x0afunction theTestConstructor(arg1, arg2, arg3) {}\x0atheTestConstructor.prototype = new theTestPrototype;\x0a\x0avar theWrappedConstructor = _st(theTestConstructor);\x0avar theResult = theWrappedConstructor._newWithValues_([1, 2, 3]);\x0aself._assert_equals_(Object.getPrototypeOf(theResult).name, 'theTestPrototype');\x0a\x0a\x22newWithValues: cannot help if the argument list is wrong, and should warn that a mistake was made.\x22\x0afunction constructionShouldFail() {var anotherResult = theWrappedConstructor._newWithValues_('This is so wrong');}\x0aself._should_raise_(_st(constructionShouldFail), smalltalk.Error);\x0a>",
 messageSends: [],
 referencedClasses: []
 }),

st/Kernel-Methods.st

@@ -125,21 +125,20 @@ newValue: anObject value: anObject2 value: anObject3
 !
 
 newWithValues: aCollection
-"I'll apply a variable number of arguments to a function, and return the object created.
-
-Note: This is apparently just what Coffeescript does; I know because I was 'inspired' by http://stackoverflow.com/a/6069331.
+"Answer an object that's been created in JS via `new` and had `self` applied to it.
+This algorithm was inspired by http://stackoverflow.com/a/6069331.
 
 Here's a general breakdown of what's going on:
 1) Create a new, blank function object.
-2) Set it's prototype to 'my' prototype. Remember, we are in a BlockClosure, and presumably this BlockClosure is wrapping a JS function, and also presumably this function is used as a constructor.
-3) Instantiate a new version of the function object we just created. This forces the interpreter to set the internal [[prototype]] property to what was set on the function before. This has to be done, as we have no access to the [[prototype]] property externally.
-4) Apply 'myself' to the object I just instantiated."
+2) Set it's prototype to `self`'s prototype. Remember, we're in a BlockClosure, and presumably this BlockClosure is wrapping a JS function, and also presumably this function is used as a constructor.
+3) Instantiate a new version of the function object just created. This forces the interpreter to set the internal [[prototype]] property to what was set on the function before. This has to be done, as we have no access to the [[prototype]] property externally.
+4) Apply `self` to the object I just instantiated."
 <
-var duck = function() {};
-duck.prototype = self.prototype;
-var duckInstance = new duck;
-var result = self.apply(duckInstance, aCollection);
-return typeof result === "object" ? result : duckInstance;
+var blankObject = function() {};
+blankObject.prototype = self.prototype;
+var newObject = new blankObject;
+var result = self.apply(newObject, aCollection);
+return typeof result === "object" ? result : newObject;
 >
 !
 

st/Kernel-Tests.st

@@ -51,16 +51,17 @@ testExceptionSemantics
 
 testNewWithValues
 <
-function theTestPrototype() {
-	this.name = "theTestPrototype";
-}
+function theTestPrototype() {this.name = "theTestPrototype";}
 function theTestConstructor(arg1, arg2, arg3) {}
 theTestConstructor.prototype = new theTestPrototype;
 
 var theWrappedConstructor = _st(theTestConstructor);
 var theResult = theWrappedConstructor._newWithValues_([1, 2, 3]);
-
 self._assert_equals_(Object.getPrototypeOf(theResult).name, 'theTestPrototype');
+
+"newWithValues: cannot help if the argument list is wrong, and should warn that a mistake was made."
+function constructionShouldFail() {var anotherResult = theWrappedConstructor._newWithValues_('This is so wrong');}
+self._should_raise_(_st(constructionShouldFail), smalltalk.Error);
 >
 !