Merge pull request #3649 from obsidian-tasks-group/issue-3647-fake-inherit-tags

docs: Show 'group by function' inheriting tags from parent task

Author: claremacrae

docs/Queries/Grouping.md

@@ -754,6 +754,17 @@ group by function task.tags.filter( (tag) => ! tag.includes("#tag") )
 
 - Create headings for all tags that do not contain "#tag".
 
+```javascript
+group by function \
+    if (task.tags.length > 0) return task.tags; \
+    return task.findClosestParentTask()?.tags ?? [];
+```
+
+- Group tag-less child tasks by any tags on their parent task:
+  - If the task has any tags on its own line, then group by those tags.
+  - Otherwise, look for the first parent task, and group by its tags.
+  - If there is no parent task, treat the tags as empty.
+
 <!-- placeholder to force blank line after included text --><!-- endInclude -->
 
 These are more complicated examples, which you might like to copy if you use tasks with [nested tags](https://help.obsidian.md/Editing+and+formatting/Tags#Nested+tags) and wish to group them at different tag nesting levels.

tests/Scripting/ScriptingReference/CustomGrouping/CustomGroupingExamples.test.other_properties_task.tags_docs.approved.md

@@ -32,5 +32,16 @@ group by function task.tags.filter( (tag) => ! tag.includes("#tag") )
 
 - Create headings for all tags that do not contain "#tag".
 
+```javascript
+group by function \
+    if (task.tags.length > 0) return task.tags; \
+    return task.findClosestParentTask()?.tags ?? [];
+```
+
+- Group tag-less child tasks by any tags on their parent task:
+  - If the task has any tags on its own line, then group by those tags.
+  - Otherwise, look for the first parent task, and group by its tags.
+  - If there is no parent task, treat the tags as empty.
+
 
 <!-- placeholder to force blank line after included text -->

tests/Scripting/ScriptingReference/CustomGrouping/CustomGroupingExamples.test.other_properties_task.tags_results.approved.txt

@@ -61,3 +61,22 @@ Create headings for all tags that do not contain "#tag".
 #project/project1
 ====================================================================================
 
+
+group by function \
+    if (task.tags.length > 0) return task.tags; \
+    return task.findClosestParentTask()?.tags ?? [];
+Group tag-less child tasks by any tags on their parent task:
+  If the task has any tags on its own line, then group by those tags.
+  Otherwise, look for the first parent task, and group by its tags.
+  If there is no parent task, treat the tags as empty.
+=>
+#context/home
+#context/work
+#multiple-tags1
+#multiple-tags2
+#project/project1
+#tag
+#tag/subtag
+#tag/subtag/sub-sub-tag
+====================================================================================
+

tests/Scripting/ScriptingReference/CustomGrouping/CustomGroupingExamples.test.ts

@@ -626,6 +626,15 @@ describe('other properties', () => {
                     'group by function task.tags.filter( (tag) => ! tag.includes("#tag") )',
                     'Create headings for all tags that do not contain "#tag"',
                 ],
+                [
+                    `group by function \\
+    if (task.tags.length > 0) return task.tags; \\
+    return task.findClosestParentTask()?.tags ?? [];`,
+                    'Group tag-less child tasks by any tags on their parent task:',
+                    '  If the task has any tags on its own line, then group by those tags.',
+                    '  Otherwise, look for the first parent task, and group by its tags.',
+                    '  If there is no parent task, treat the tags as empty.',
+                ],
             ],
             SampleTasks.withRepresentativeTags(),
         ],