docs: More group limits docs (+minor test & refactor) (#1973)

* docs: Add 'limit groups' options to Quick Reference page

* docs: Minor improvements to Limiting docs

* docs: Add 'limit groups' to "What's new?"

* docs: Slightly clarify headings in Limiting.md

* docs: Add link in Grouping.md to 'limit groups' feature

* docs: Add order of reoccurring tasks option to "What's new?"

* test: Test explanation of both limit options.

There is a curious double-blank line, which I intend to ignore for now.

* fix: Explanation now says 'limit groups' ignored if no groups

* refactor: Extract method Query.explainQueryLimits()

* refactor: Remove unnecessary parameter from Query.explainQueryLimits()

* refactor: Remove some repetition in Query.explainQueryLimits()

docs/Getting Started/Recurring Tasks.md

@@ -15,7 +15,7 @@ When you toggle the status of a recurring task to anything but "todo" (i.e. "don
 
 In addition, _a new task will be put one line above the original task_ by default.
 
-See [[#Location of the new task]] below, for how to change this behaviour and make the new task appear _on the line below the original task_.
+See [[#Order of the new task]] below, for how to change this behaviour and make the new task appear _on the line below the original task_.
 
 The new task will have updated dates based off the original task.
 
@@ -74,14 +74,14 @@ You can validate that tasks understands your rule by using the `Tasks: Create or
 
 ---
 
-## Location of the new task
+## Order of the new task
 
 Use this setting to control where the recurring task is inserted. The default is to put the new task before the original one.
 
 ![Setting for next recurrence appearance](../../images/settings-recurrence-location.png)
 
 > [!released]
-> Control of the location of the new task was introduced in Tasks X.Y.Z
+> Control of the location (or order) of the new task was introduced in Tasks X.Y.Z
 
 ---
 

docs/Getting Started/Settings.md

@@ -26,6 +26,6 @@ For convenience, here is a list of all those documentation pages (in the order t
 - [[Global Query]]
 - [[Status Settings]]
 - [[Dates#Date-tracking settings]]
-- [[Recurring Tasks#Location of the new task]]
+- [[Recurring Tasks#Order of the new task]]
 - [[Auto-Suggest]]
 - [[Create or edit Task#Turning off keyboard shortcuts]]

docs/Introduction.md

@@ -6,6 +6,8 @@ publish: true
 
 ## What's New?
 
+- X.Y.Z: 🔥 Add [[Limiting#Limit number of tasks in each group|limiting tasks per group]]
+- X.Y.Z: 🔥 Add option to control the [[Recurring Tasks#Order of the new task|order of new recurring tasks]]
 - 3.7.0: 🔥 Add [[Grouping#Reversing groups|reverse sorting of groups]]
 - 3.6.0: 🔥 Add [[Grouping#Other task properties|group by urgency]]
 - 3.6.0: 🔥 Add [[Sorting#Other task properties|sort by recurring]]

docs/Queries/Grouping.md

@@ -117,7 +117,9 @@ See the [screenshots below](#screenshots) for how this looks in practice.
 > [!info]
 > Headings are displayed in case-sensitive alphabetical order, not the original order.
 
-## Reversing groups
+## Refining groups
+
+### Reversing groups
 
 > [!released]
 > Reversing of group headings was introduced in Tasks 3.7.0.
@@ -139,6 +141,12 @@ For example:
 >
 > The [[Sorting|sort by]] facility, by contrast, controls the order in which displays are displayed *inside* each group.
 
+### Limiting group size
+
+You can limit the number of tasks in each group, perhaps to work on the most important things first.
+
+See [[Limiting#Limit number of tasks in each group|Limit number of tasks in each group]].
+
 ## Notes
 
 > [!info]

docs/Queries/Limiting.md

@@ -4,18 +4,26 @@ publish: true
 
 # Limiting
 
-## Total tasks
+## Limit total number of tasks
+
+You can limit the total number of tasks to show as query results.
 
-You can limit the number of total tasks to show as query results.
 Use the query string `limit to <number> tasks`.
-This will only list the `<number>` first results of the query.
+This will only list the first `<number>` results of the query (after sorting).
 
 Shorthand is `limit <number>`.
 
-## Tasks per group
+## Limit number of tasks in each group
+
+You can also limit the allowed number of tasks in each group, if [[Grouping|grouping]] is used. Otherwise this limit is ignored.
 
-You can also limit the max number of tasks in groups if grouping is used. Otherwise this limit is ignored.
 Use the query string `limit groups to <number> tasks`.
-This will only list the `<number>` first tasks in each group from the results of the query.
+This will only list the first `<number>` tasks in each group from the results of the query.
 
 Shorthand is `limit groups <number>`.
+
+> [!NOTE]
+> `limit groups` instructions are ignored if there are no `group by` instructions in the Tasks query.
+
+> [!released]
+> `limit groups to <number> tasks` was introduced in Tasks X.Y.Z.

docs/Quick Reference.md

@@ -24,7 +24,7 @@ This table summarizes the filters and other options available inside a `tasks` b
 | **[[Filters#Recurrence\|Recurrence]]**                                                                                                                                                                                                                                                          |                                             |                        |                        |
 | `is recurring`<br>`is not recurring`                                                                                                                                                                                                                                                            | `sort by recurring`                         | `group by recurring`   |                        |
 | `recurrence (includes, does not include) <string>`<br>`recurrence (regex matches, regex does not match) /regex/i`                                                                                                                                                                               |                                             | `group by recurrence`  | `hide recurrence rule` |
-| **[[Filters#Priority\|Priority]]** and **[[Urgency\|urgency]]**                                                                                                                                                                                                                                          |                                             |                        |                        |
+| **[[Filters#Priority\|Priority]]** and **[[Urgency\|urgency]]**                                                                                                                                                                                                                                 |                                             |                        |                        |
 | `priority is (above, below, not)? (low, none, medium, high)`                                                                                                                                                                                                                                    | `sort by priority`                          | `group by priority`    | `hide priority`        |
 |                                                                                                                                                                                                                                                                                                 | `sort by urgency`                           | `group by urgency`     | `show urgency`         |
 | **[[Filters#Filters for File Properties\|File properties]]**                                                                                                                                                                                                                                    |                                             |                        |                        |
@@ -48,6 +48,7 @@ This table summarizes the filters and other options available inside a `tasks` b
 | **Other Filter Options**                                                                                                                                                                                                                                                                        |                                             |                        |                        |
 | `exclude sub-items`                                                                                                                                                                                                                                                                             |                                             |                        |                        |
 | `limit to <number> tasks`<br>`limit <number>`                                                                                                                                                                                                                                                   |                                             |                        |                        |
+| `limit groups to <number> tasks`<br>`limit groups <number>`                                                                                                                                                                                                                                     |                                             |                        |                        |
 | **Other Layout Options**                                                                                                                                                                                                                                                                        |                                             |                        |                        |
 | `hide edit button`                                                                                                                                                                                                                                                                              |                                             |                        |                        |
 | `hide task count`                                                                                                                                                                                                                                                                               |                                             |                        |                        |

src/Query/Query.ts

@@ -109,29 +109,37 @@ export class Query implements IQuery {
                 result += this.filters[i].explainFilterIndented('');
             }
         }
+        result += this.explainQueryLimits();
 
-        if (this._limit !== undefined) {
-            result += `\n\nAt most ${this._limit} task`;
-            if (this._limit !== 1) {
-                result += 's';
-            }
-            result += '.\n';
+        const { debugSettings } = getSettings();
+        if (debugSettings.ignoreSortInstructions) {
+            result +=
+                "\n\nNOTE: All sort instructions, including default sort order, are disabled, due to 'ignoreSortInstructions' setting.";
         }
 
-        if (this._taskGroupLimit !== undefined) {
-            result += `\n\nAt most ${this._taskGroupLimit} task`;
-            if (this._taskGroupLimit !== 1) {
-                result += 's';
+        return result;
+    }
+
+    private explainQueryLimits() {
+        let result = '';
+
+        function getPluralisedText(limit: number) {
+            let text = `\n\nAt most ${limit} task`;
+            if (limit !== 1) {
+                text += 's';
             }
-            result += ' per group.\n';
+            return text;
         }
 
-        const { debugSettings } = getSettings();
-        if (debugSettings.ignoreSortInstructions) {
-            result +=
-                "\n\nNOTE: All sort instructions, including default sort order, are disabled, due to 'ignoreSortInstructions' setting.";
+        if (this._limit !== undefined) {
+            result += getPluralisedText(this._limit);
+            result += '.\n';
         }
 
+        if (this._taskGroupLimit !== undefined) {
+            result += getPluralisedText(this._taskGroupLimit);
+            result += ' per group (if any "group by" options are supplied).\n';
+        }
         return result;
     }
 

tests/Query.test.ts

@@ -885,7 +885,21 @@ At most 0 tasks.
 
             const expectedDisplayText = `No filters supplied. All tasks will match the query.
 
-At most 4 tasks per group.
+At most 4 tasks per group (if any "group by" options are supplied).
+`;
+            expect(query.explainQuery()).toEqual(expectedDisplayText);
+        });
+
+        it('should explain all limit options', () => {
+            const input = 'limit 127\nlimit groups to 8 tasks';
+            const query = new Query({ source: input });
+
+            const expectedDisplayText = `No filters supplied. All tasks will match the query.
+
+At most 127 tasks.
+
+
+At most 8 tasks per group (if any "group by" options are supplied).
 `;
             expect(query.explainQuery()).toEqual(expectedDisplayText);
         });