improved sort documentation (#82)

README.md

@@ -157,13 +157,15 @@ const isProperSupersetABC = properSuperset(setA, setB, setC);
 
 ## Set Ordering:
 
-### sort:
+### sort: `A ⇅`
 An immutable sorting operation for sets.
+
+![sort visual][]
 ```typescript
 import { sort } from 'set-utilities';
 
-const sorted = sort(setA);
-const sortedByComparator = sort(setA, comparatorFunction);
+const sortedA = sort(setA);
+const sortedB = sort(setB, compareFunction);
 ```
 
 
@@ -205,3 +207,5 @@ const sortedByComparator = sort(setA, comparatorFunction);
 [proper subset visual]: https://github.com/kubikowski/set-utilities/wiki/assets/proper-subset.svg
 [superset visual]: https://github.com/kubikowski/set-utilities/wiki/assets/superset.svg
 [proper superset visual]: https://github.com/kubikowski/set-utilities/wiki/assets/proper-superset.svg
+
+[sort visual]: https://github.com/kubikowski/set-utilities/wiki/assets/sort.svg

src/ordering/sort.function.ts

@@ -2,11 +2,15 @@ export function sort<T>(set: Set<T>, compareFunction?: (a: T, b: T) => number):
 export function sort<T>(set: ReadonlySet<T>, compareFunction?: (a: T, b: T) => number): ReadonlySet<T>;
 
 /**
- * Unlike JavaScript's native Array sort, this implementation
- * of Set sort does not modify the original Set.
+ * Unlike JavaScript's native array sort, this set sort
+ * does not modify the ordering of the original set.
  *
- * Instead, it returns a new sorted Set
- * with the same elements contained in the original.
+ * Instead, it returns a new sorted set with
+ * the same elements contained in the original.
+ *
+ * Sort is often notated A ⇅,
+ * or specifically as A ↑ or A ↓ depending on whether
+ * the sort order is ascending or descending respectively.
  */
 export function sort<T, S extends ReadonlySet<T>>(set: S, compareFunction?: (a: T, b: T) => number): S {
 	return new Set<T>(Array.from(set).sort(compareFunction)) as ReadonlySet<T> as S;