Repository: obsidian-tasks-group/obsidian-tasks
Pull request #1973 (2023-05-27 15:55:21)

docs: More group limits docs (+minor test & refactor)
<!--- Provide a general summary of your changes in the Title above -->

# Description

Just a few minor improvements to docs, tests and code, getting reading for the next release.

## Motivation and Context

Mainly to make new features in the next release more discoverable.

## How has this been tested?

- Viewing the docs in Obsidian
- Running the code in Demo 

## Screenshots (if appropriate)

## Types of changes

<!--- What types of changes does your code introduce? Put an `x` in all the boxes that apply: -->

Changes visible to users:

- [x] **Documentation** (prefix: `docs` - improvements to any documentation content **for users**)

Internal changes:

- [x] **Refactor** (prefix: `refactor` - non-breaking change which only improves the design or structure of existing code, and making no changes to its external behaviour)
- [x] **Tests** (prefix: `test` - additions and improvements to unit tests and the smoke tests)

## Checklist

<!--- Go over all the following points, and put an `x` in all the boxes that apply. -->
<!--- If you're unsure about any of these, don't hesitate to ask. We're here to help! -->

- [x] My code follows the code style of this project and passes `yarn run lint`.
- [x] My change requires a change to the documentation.
- [x] I have [updated the documentation](https://publish.obsidian.md/tasks-contributing/Documentation/About+Documentation) accordingly.
- [x] My change has adequate [Unit Test coverage](https://publish.obsidian.md/tasks-contributing/Testing/About+Testing).

## Terms

<!--
By submitting this pull request, you must agree to follow our
[contributing guide](https://publish.obsidian.md/tasks-contributing) and
[Code of Conduct](https://github.com/obsidian-tasks-group/obsidian-tasks/blob/main/CODE_OF_CONDUCT.md).
Put an x in the boxes to confirm you agree.
-->

- [x] My contribution follow this project's [contributing guide](https://publish.obsidian.md/tasks-contributing)
- [x] I agree to follow this project's [Code of Conduct](https://github.com/obsidian-tasks-group/obsidian-tasks/blob/main/CODE_OF_CONDUCT.md)



Patch:
diff --git a/docs/Getting Started/Recurring Tasks.md b/docs/Getting Started/Recurring Tasks.md
index 2362d771..7aabd89d 100644
--- a/docs/Getting Started/Recurring Tasks.md
+++ b/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
 
 ---
 
diff --git a/docs/Getting Started/Settings.md b/docs/Getting Started/Settings.md
index bd160cf0..23ec87e9 100644
--- a/docs/Getting Started/Settings.md
+++ b/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]]
diff --git a/docs/Introduction.md b/docs/Introduction.md
index 58834a04..f4e881d5 100644
--- a/docs/Introduction.md
+++ b/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]]
diff --git a/docs/Queries/Grouping.md b/docs/Queries/Grouping.md
index c14f7af4..432db8b5 100644
--- a/docs/Queries/Grouping.md
+++ b/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]
diff --git a/docs/Queries/Limiting.md b/docs/Queries/Limiting.md
index 21a99ecf..1f5cef44 100644
--- a/docs/Queries/Limiting.md
+++ b/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.
diff --git a/docs/Quick Reference.md b/docs/Quick Reference.md
index d60a1746..8001fbc7 100644
--- a/docs/Quick Reference.md
+++ b/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`                                                                                                                                                                                                                                                                               |                                             |                        |                        |
diff --git a/src/Query/Query.ts b/src/Query/Query.ts
index c82306c2..ca644c8c 100644
--- a/src/Query/Query.ts
+++ b/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;
     }
 


Test patch:
diff --git a/tests/Query.test.ts b/tests/Query.test.ts
index 5c40ca7f..bcc93a10 100644
--- a/tests/Query.test.ts
+++ b/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);
         });