Merge pull request #3626 from obsidian-tasks-group/issue-3625-return-string

docs: String "return" in function returns "undefined" (#3625)

Author: claremacrae

docs/Scripting/Expressions.md

@@ -86,6 +86,8 @@ As of Tasks 4.4.0, it is also possible to use more complex constructs in express
 - `if` statements
 - functions
 
+Note in the examples below that if `return` appears anywhere in the expression, you must write your own `return` statement, to prevent the result being `undefined`.
+
 As of Tasks 5.0.0, it is also possible to make longer expressions more readable using [[Line Continuations|line continuations]].
 
 <!-- placeholder to force blank line before included text --><!-- include: Expression.test.Expression_returns_and_functions.approved.md -->
@@ -97,6 +99,12 @@ return 42
 const x = 1 + 1; return x * x
 => 4
 
+'any text that contains the word return'
+=> undefined
+
+return 'any text that contains the word return'
+=> 'any text that contains the word return'
+
 if (1 === 1) { return "yes"; } else { return "no" }
 => 'yes'
 

tests/Scripting/Expression.test.Expression_returns_and_functions.approved.md

@@ -7,6 +7,12 @@ return 42
 const x = 1 + 1; return x * x
 => 4
 
+'any text that contains the word return'
+=> undefined
+
+return 'any text that contains the word return'
+=> 'any text that contains the word return'
+
 if (1 === 1) { return "yes"; } else { return "no" }
 => 'yes'
 

tests/Scripting/Expression.test.ts

@@ -151,6 +151,12 @@ describe('Expression', () => {
         const expressions = [
             'return 42',
             'const x = 1 + 1; return x * x',
+
+            // Presence of 'return', even if in a string, makes Tasks plugin think it does not need to add 'return':
+            "'any text that contains the word return'",
+            // So if the text 'return' appears anywhere in the expression, an explicit 'return' instruction must be supplied:
+            "return 'any text that contains the word return'",
+
             'if (1 === 1) { return "yes"; } else { return "no" }',
             `function f(value) {                 \\
     if (value === 1 ) {             \\