Updated documentation on SORT

Author: rjose

docs/v2/global_module.md

@@ -528,20 +528,44 @@ For a record, this is a no-op.
 
 
 ### SORT
+
 `( array -- array )`
 
-`( record -- record )`
+Sorts elements of an array by a default comparison.
+
+Example:
 
-Sorts elements of an array by a default comparison. For a record, this is a no-op.
+```
+[3 1 2 4] SORT                  #  [1 2 3 4]
 
+["beta" "gamma" "alpha"] SORT   #  ["alpha" "beta" "gamma"]
+```
 
 ### SORT-w/FORTHIC
+
 `( array forthic -- array )`
 
-`( record forthic -- record )`
+Sorts elements of an array using a `forthic` string to compare them. This is useful if you
+want to sort values in a custom way, or if you want to sort an array of records.
+
+Example:
+
+```
+# Sorting by risk
+: RISK>ORDER   [
+    ["red"     1]
+    ["yellow"  2]
+    ["green"]  3]
+] REC SWAP REC@;
+
+["yellow" "red" "green" "red"]  "RISK>ORDER" SORT-w/FORTHIC   #  ["red" "red" "yellow" "green"]
+
+# Sorting by assignee
+: TICKET>ASSIGNEE   "Assignee" REC@;
+
+TICKETS "TICKET>ASSIGNEE"  SORT-w/FORTHIC
+```
 
-Sorts elements of an array using a `forthic` string to return a value for comparison. For
-a record, this is a no-op.
 
 ### SORT-w/KEY-FUNC
 `( array key_func -- array )`

docs/v3/global_module.md

@@ -468,6 +468,7 @@ For a record, this is a no-op.
 
 
 ### SORT
+
 `( array -- array )`
 
 Sorts elements of an array by a default comparison. For a record, this is a no-op.
@@ -479,6 +480,31 @@ If `<comparator> !COMPARATOR` is called just before `SORT`, the specified `compa
 used to compare elements for sort. The `comparator` may be a Forthic string or it may be a
 function.
 
+Example:
+
+```
+# Sorting with default comparator
+[3 1 2 4] SORT                  #  [1 2 3 4]
+
+["beta" "gamma" "alpha"] SORT   #  ["alpha" "beta" "gamma"]
+
+
+# Sorting by risk using a comparator
+: RISK>ORDER   [
+    ["red"     1]
+    ["yellow"  2]
+    ["green"]  3]
+] REC SWAP REC@;
+
+["yellow" "red" "green" "red"]  "RISK>ORDER" !COMPARATOR SORT   #  ["red" "red" "yellow" "green"]
+
+
+# Sorting by assignee using a comparator
+: TICKET>ASSIGNEE   "Assignee" REC@;
+
+TICKETS "TICKET>ASSIGNEE" !COMPARATOR SORT
+```
+
 
 ### FIELD-KEY-FUNC
 `( field -- key_func )`