- Added specific tests for sorter and sorterDesc

- Minor improvements in documentation

src/object.js

@@ -330,7 +330,7 @@ var hasOwnKey = _curry(hasOwn, 2, true);
  *     luckyNumbers: [13, 17]
  * });
  *
- * // Any of these statements will fail and possibly
+ * // All of these statements will fail and possibly
  * // throw a TypeError (see the function description)
  * user.name = "Joe";
  * delete user.name;

src/sort.js

@@ -149,8 +149,9 @@ function insert (array, element) {
  * Returns a [stably]{@link https://en.wikipedia.org/wiki/Sorting_algorithm#Stability} sorted copy of an
  * array-like object using the given criteria.<br/>
  * Sorting criteria are built using Lamb's {@link module:lamb.sorter|sorter} function, but you can also
- * pass simple "reader" functions and default ascending sorters will be built.<br/>
- * A "reader" is a function that evaluates the array element and supplies the value to be used in the comparison.
+ * pass simple "reader" functions and default ascending sorters will be built for you.<br/>
+ * A "reader" is a function that evaluates the array element and supplies the value to be used in the comparison.<br/>
+ * Please note that if the arguments received by the default comparer aren't of the same type, they will be compared as strings.
  *
  * @example <caption>Stable sort:</caption>
  * var persons = [

test/spec/sortSpec.js

@@ -210,4 +210,53 @@ describe("lamb.sort", function () {
             expect(lamb.sortWith(localeSorterDesc)(chars)).toEqual(charsDesc);
         });
     });
+
+    describe("sorter / sorterDesc", function () {
+        var myComparer = jasmine.createSpy().and.returnValue("foo");
+        var myReader = jasmine.createSpy().and.callFake(lamb.getKey("a"));
+        var foo = {a: 1};
+        var bar = {a: 2};
+
+        afterEach(function () {
+            myComparer.calls.reset();
+            myReader.calls.reset();
+        });
+
+        it("should build a sorting criterion", function () {
+            var sorterAsc = lamb.sorter();
+            var sorterDesc = lamb.sorterDesc();
+
+            expect(sorterAsc.isDescending).toBe(false);
+            expect(sorterDesc.isDescending).toBe(true);
+            expect(typeof sorterAsc.compare).toBe("function");
+            expect(typeof sorterDesc.compare).toBe("function");
+            expect(sorterAsc.compare.length).toBe(2);
+            expect(sorterDesc.compare.length).toBe(2);
+        });
+
+        it("should use a custom comparer if supplied with one", function () {
+            expect(lamb.sorter(null, myComparer).compare(foo, bar)).toBe("foo");
+        });
+
+        it("should pass values directly to the comparer if there's no reader function or if the reader is the identity function", function () {
+            lamb.sorter(lamb.identity, myComparer).compare(foo, bar);
+            lamb.sorterDesc(null, myComparer).compare(foo, bar);
+
+            expect(myComparer).toHaveBeenCalledTimes(2);
+            expect(myComparer.calls.argsFor(0)[0]).toBe(foo);
+            expect(myComparer.calls.argsFor(0)[1]).toBe(bar);
+            expect(myComparer.calls.argsFor(1)[0]).toBe(foo);
+            expect(myComparer.calls.argsFor(1)[1]).toBe(bar);
+        });
+
+        it("should use a custom resader if supplied with one", function () {
+            lamb.sorter(myReader, myComparer).compare(foo, bar);
+
+            expect(myReader).toHaveBeenCalledTimes(2);
+            expect(myReader.calls.argsFor(0)[0]).toBe(foo);
+            expect(myReader.calls.argsFor(1)[0]).toBe(bar);
+            expect(myComparer).toHaveBeenCalledTimes(1);
+            expect(myComparer).toHaveBeenCalledWith(1, 2);
+        });
+    });
 });