docs: Document addition of query.allTasks to custom searches

Author: claremacrae

docs/Introduction.md

@@ -13,20 +13,22 @@ _In recent [releases](https://github.com/obsidian-tasks-group/obsidian-tasks/rel
     Move the older ones down to the top of the comment block below...
 -->
 
+- X.Y.Z:
+  - `query.allTasks` is now available in custom searches: see [[Query Properties#Values for Query Search Properties|query search properties]].
 - 6.0.0:
   - Add [[Custom Sorting|custom sorting]].
   - Document the [[Sorting#Default sort order|default sort order]].
   - **Warning**: This release contains some **bug-fixes** to **sorting** and to treatment of **invalid dates**.
     - The changes are detailed in [[breaking changes#Tasks 6.0.0 (19 January 2024)|breaking changes]], even though they are all improvements to the previous behaviour.
     - You may need to update any CSS snippets for the Edit or Postpone buttons: see [[How to style buttons]].
-- 5.6.0:
-  - The [[Postponing|postpone]] menu now offers `today` and `tomorrow`.
-- 5.5.0:
-  - The [[Create or edit Task]] modal can now edit Created, Done and Cancelled dates
-  - Add support for [[Dates#Cancelled date|cancelled dates]].
 
 > [!Released]- Earlier Releases
 >
+> - 5.6.0:
+>   - The [[Postponing|postpone]] menu now offers `today` and `tomorrow`.
+> - 5.5.0:
+>   - The [[Create or edit Task]] modal can now edit Created, Done and Cancelled dates
+>   - Add support for [[Dates#Cancelled date|cancelled dates]].
 > - 5.4.0:
 >   - Add [[Layout#Full Mode|'full mode']] to turn off `short mode`.
 >   - Add any [[Grouping|'group by']] and [[Sorting|'sort by']] instructions to [[Explaining Queries|explain]] output.

docs/Scripting/Query Properties.md

@@ -42,3 +42,17 @@ This page documents all the available pieces of information in Queries that you
 1. The presence of `.md` filename extensions is chosen to match the existing conventions in the Tasks filter instructions [[Filters#File Path|path]] and [[Filters#File Name|filename]].
 1. `query.file.pathWithoutExtension` was added in Tasks 4.8.0.
 1. `query.file.filenameWithoutExtension` was added in Tasks 4.8.0.
+
+## Values for Query Search Properties
+
+<!-- placeholder to force blank line before included text --><!-- include: QueryProperties.test.query_search_properties.approved.md -->
+
+| Field | Type | Example |
+| ----- | ----- | ----- |
+| `query.allTasks` | `Task[]` | `[... an array with all the Tasks-tracked tasks in the vault ...]` |
+
+<!-- placeholder to force blank line after included text --><!-- endInclude -->
+
+1. `query.allTasks` provides access to all the tasks that Tasks has read from the vault.
+1. See [[Task Properties]] for the available properties on each task in `query.allTasks`.
+1. `query.allTasks` was added in Tasks X.Y.Z.

tests/Scripting/QueryProperties.test.query_search_properties.approved.md

@@ -0,0 +1,8 @@
+<!-- placeholder to force blank line before included text -->
+
+| Field | Type | Example |
+| ----- | ----- | ----- |
+| `query.allTasks` | `Task[]` | `[... an array with all the Tasks-tracked tasks in the vault ...]` |
+
+
+<!-- placeholder to force blank line after included text -->

tests/Scripting/QueryProperties.test.ts

@@ -10,7 +10,9 @@ describe('query', () => {
     function verifyFieldDataForReferenceDocs(fields: string[]) {
         const markdownTable = new MarkdownTable(['Field', 'Type', 'Example']);
         const path = 'root/sub-folder/file containing query.md';
-        const task = new TaskBuilder().build();
+        const task = new TaskBuilder()
+            .description('... an array with all the Tasks-tracked tasks in the vault ...')
+            .build();
         const queryContext = makeQueryContextWithTasks(path, [task]);
         for (const field of fields) {
             const value1 = parseAndEvaluateExpression(task, field, queryContext);
@@ -34,4 +36,8 @@ describe('query', () => {
             'query.file.filenameWithoutExtension',
         ]);
     });
+
+    it('search properties', () => {
+        verifyFieldDataForReferenceDocs(['query.allTasks']);
+    });
 });

tests/Scripting/ScriptingTestHelpers.ts

@@ -1,6 +1,7 @@
 import moment from 'moment';
 import { TasksDate } from '../../src/Scripting/TasksDate';
 import { TaskRegularExpressions } from '../../src/Task/TaskRegularExpressions';
+import { Task } from '../../src/Task/Task';
 
 export function formatToRepresentType(x: any): string {
     if (typeof x === 'string') {
@@ -11,6 +12,10 @@ export function formatToRepresentType(x: any): string {
         return `moment('${x.format(TaskRegularExpressions.dateTimeFormat)}')`;
     }
 
+    if (x instanceof Task) {
+        return x.description;
+    }
+
     if (x instanceof TasksDate) {
         return x.formatAsDateAndTime();
     }
@@ -33,7 +38,7 @@ export function addBackticks(x: any) {
     return quotedText;
 }
 
-export function determineExpressionType(value: any) {
+export function determineExpressionType(value: any): string {
     if (value === null) {
         return 'null';
     }
@@ -42,13 +47,17 @@ export function determineExpressionType(value: any) {
         return 'Moment';
     }
 
+    if (value instanceof Task) {
+        return 'Task';
+    }
+
     if (value instanceof TasksDate) {
         return 'TasksDate';
     }
 
     if (Array.isArray(value)) {
         if (value.length > 0) {
-            return `${typeof value[0]}[]`;
+            return `${determineExpressionType(value[0])}[]`;
         } else {
             return 'any[]';
         }