docs: Document 'sort by function'.

Author: claremacrae

docs/Queries/Sorting.md

@@ -13,6 +13,7 @@ publish: true
 This page is long. Here are some links to the main sections:
 
 - [[#Default sort order]]
+- [[#Custom Sorting]]
 - [[#Sort by Task Statuses]]
 - [[#Sort by Dates in Tasks]]
 - [[#Sort by Other Task Properties]]
@@ -51,7 +52,16 @@ However, any `sort by` instructions in queries take precedence over these defaul
 
 ## Custom Sorting
 
-==TODO Populate this section==
+> [!released]
+> `sort by function` was introduced in Tasks X.Y.Z.
+
+Tasks provides many built-in sorting options, but sometimes they don't quite do what is wanted by all users.
+
+Now Tasks has a powerful mechanism for you to create your own **custom sort orders**, offering incredible flexibility.
+
+There are many examples of the custom filtering instruction `sort by function` in the documentation below, with explanations, for when the instructions built in to Tasks do not satisfy your preferences.
+
+You can find out more about this very powerful facility in [[Custom Sorting]].
 
 ## Sort by Task Statuses
 
@@ -61,6 +71,9 @@ For more information, including adding your own customised statuses, see [[Statu
 
 - `sort by status` (done or todo)
 
+> [!Tip]
+> `sort by status.type` gives a much more useful sort order than `sort by status`. See [[#Status Type#]] below.
+
 Since Tasks X.Y.Z, **[[Custom Sorting|custom sorting]] by status** is now possible.
 
 <!-- placeholder to force blank line before included text --><!-- include: CustomSortingExamples.test.other_properties_task.isDone_docs.approved.md -->

docs/Scripting/Custom Sorting.md

@@ -13,6 +13,8 @@ publish: true
 
 - Define your own custom task sort order, using JavaScript expressions such as:
   - `sort by function task.description.length`
+  - We call the result of this expression a **sort key**.
+  - Tasks with **lower values** from the sort key expression are sorted **before** tasks with **higher expression** values.
 - There are examples in [[Sorting]].
   - Search for `sort by function` in that file.
 - Find all the **supported tasks properties** in [[Task Properties]] and [[Quick Reference]].
@@ -48,15 +50,17 @@ The instructions look like this:
 - `sort by function <expression>`
 - `sort by function reverse <expression>`
 
-The expression is evaluated (calculated) on each task that matches your query, and the expression result is used as the sort key for the task.
+The expression is evaluated (calculated) on each task that matches your query, and the expression result is used as the **sort key** for the task.
 
-==TODO Update this==
+This table shows how the supported sort key value types behave.
 
-| Desired heading                                                             | Values that you can return                                                                             |
-| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| A single sort name for the task                                            | A single value, such as `'sort name'`.<br>An array, with a single value in, such as `['sort name']`. |
-| Display the task potentially more than once (as is done by `sort by tags`) | An array of values, such as:<br>`['heading 1', 'heading 2']`                                             |
-| No heading                                                                  | `null`<br>Empty string `''`<br>Empty array `[]`                                                        |
+| Sort key expression types          | Values that you can return                                                                                                                                                                  |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Strings                            | Example: `sort by function task.originalMarkdown`<br>Tasks are sorted alphabetically by the string key values. The sort is case-sensitive. It is aware of numbers and sorts them logically. |
+| Numbers                            | Example: `sort by function task.description.length`<br>Numbers are sorted in ascending order. The lower the number, the earlier the task is sorted.                                         |
+| Boolean values: `true` and `false` | Example: `sort by function task.status.name.includes('!!')` <br>Tasks with sort key `true` sort before ones with `false`.                                                                   |
+| `TasksDate` and `Moment` objects   | Example: `sort by function task.created`<br>See [[Sorting#How dates are sorted\|How dates are sorted]].                                                                                     |
+| `null`                             | `null` sorts after valid `TasksDate` and `Moment` objects, and before all other sort key values.                                                                                                                                                                                            |
 
 The `expression` can:
 
@@ -65,19 +69,15 @@ The `expression` can:
 
 The `expression` must:
 
-==TODO Update this==
-
-- use properties on a given task, such as `task.description`, `task.status.name`
-  - See the reference page [[Task Properties]] for all the available properties
-- return one of:
-  - either a single value of any type that can be converted to string
-  - or an array of values (in which case, the task will be displayed multiple times, once under each heading generated from the array)
+- use properties on a given task, such as `task.description`, `task.status.name`.
+  - See the reference page [[Task Properties]] for all the available properties.
+- return one of types of values listed in the table above.
 
 ## Example custom sorts
 
 Below are some examples to give a flavour of what can be done with custom sorts.
 
-You can find many more examples by searching for `sort by function` in the [[Sorting]] page.
+You can find some more examples by searching for `sort by function` in the [[Sorting]] page.
 
 ### Text property examples
 
@@ -109,6 +109,11 @@ sort by function \
 
 ### Date property examples
 
+Useful sections:
+
+- [[Task Properties#Values in TasksDate Properties|Values in TasksDate Properties]]
+- [[Sorting#How dates are sorted|How dates are sorted]]
+
 <!-- placeholder to force blank line before included text --><!-- include: CustomSortingExamples.test.dates_task.due_docs.approved.md -->
 
 ```javascript
@@ -134,6 +139,10 @@ sort by function reverse task.urgency
 
 ### File property examples
 
+Useful sections:
+
+- [[Task Properties#Values for File Properties|Values for File Properties]]
+
 <!-- placeholder to force blank line before included text --><!-- include: CustomSortingExamples.test.file_properties_task.file.folder_docs.approved.md -->
 
 ```javascript
@@ -153,28 +162,11 @@ sort by function task.file.path === query.file.path
 
 ## Troubleshooting
 
-> [!Warning]
-> Currently most types of error in function expressions are only detected when the search runs.
->
-> This means that error messages are displayed in the sort headings, when results are viewed.
+> [!Tip]
+> To test the values obtained from your sort key, replace `sort by` with `group by`. The generated group headings provide a sort of "debugger" to show expression values.
 >
-> In a future release, we plan to show errors in formulae when the query block is being read.
+> However, be aware that whilst  `group by` expressions can return arrays of values, `sort by` does not yet support arrays.
 
-### Syntax error
-
-The following example gives an error:
-
-````text
-```tasks
-sort by function hello
-```
-````
-
-gives this heading name:
-
-```text
-##### Error: Failed calculating expression "hello". The error message was: hello is not defined
-```
+## Limitations of Custom Sorting
 
-> [!todo]
-> Do syntax-error checking when parsing the instruction
+- Arrays cannot yet be used as sort keys, as we have not figured out the appropriate way to sort arrays of different lengths.

docs/Support and Help/Known Limitations.md

@@ -71,6 +71,10 @@ This page gathers together all the documentation on known limitations of the plu
 
 ![[Regular Expressions#Known limitations]]
 
+## Queries: Custom Sorting
+
+![[Custom Sorting#Limitations of Custom Sorting]]
+
 ## Settings: Status Settings
 
 ![[Status Settings#Limitations and Issues]]