Update timer docs

README.md

@@ -59,11 +59,13 @@ By default, openHAB ships with an older JavaScript runtime based on the Nashorn
 ### Custom Installation
 
 On openHABian:
+
 - Open the openHABian config tool: `sudo openhabian-config`.
 - Select `40 | openHAB Related`.
 - Select `46 | Install openhab-js`.
 
 Manually:
+
 - Go to the JavaScript user scripts directory: `cd $OPENHAB_CONF/automation/js`.
 - You may need to install `npm`.
 - Install the latest release: Run `npm i openhab`.
@@ -526,26 +528,71 @@ Replace `<url>` with the request url.
 See [openhab-js : actions.ScriptExecution](https://openhab.github.io/openhab-js/actions.html#.ScriptExecution) for complete documentation.
 
 ```javascript
-let now = time.ZonedDateTime.now();
+var now = time.ZonedDateTime.now();
 
 // Function to run when the timer goes off.
 function timerOver () {
   console.info('The timer is over.');
 }
 
 // Create the Timer.
-this.myTimer = actions.ScriptExecution.createTimer('My Timer', now.plusSeconds(10), timerOver);
+var myTimer = actions.ScriptExecution.createTimer('My Timer', now.plusSeconds(10), timerOver);
 
 // Cancel the timer.
-this.myTimer.cancel();
+myTimer.cancel();
 
 // Check whether the timer is active. Returns true if the timer is active and will be executed as scheduled.
-let active = this.myTimer.isActive();
+var active = myTimer.isActive();
 
 // Reschedule the timer.
-this.myTimer.reschedule(now.plusSeconds(5));
+myTimer.reschedule(now.plusSeconds(5));
+```
+
+If you need to pass some variables to the timer, there are two options to do so:
+
+**Use a function generator** <!-- markdownlint-disable-line MD036 -->
+
+This allows you to pass variables to the timer‘s callback function at timer creation.
+The variables can not be mutated after the timer function generator was used to create the function.
+
+```javascript
+var now = time.ZonedDateTime.now();
+
+// Function to run when the timer goes off.
+function timerOver (myVariable) {
+  return function () {
+    console.info('The timer is over. myVariable is: ' + myVariable);
+  }
+}
+
+// Create the Timer.
+var myTimer = actions.ScriptExecution.createTimer('My Timer', now.plusSeconds(10), timerOver('Hello world!'));
 ```
 
+**Pass a single variable to the timer** <!--markdownlint-disable-line MD036 -->
+
+This allows you to pass a single variable to the timer's callback function.
+Variables can be mutated (changed) after the timer has been created.
+Be aware that this can lead to unattended side effects, e.g. when you change the variable after timer creation, which can make debugging quite difficult!
+
+```javascript
+var now = time.ZonedDateTime.now();
+
+// Function to run when the timer goes off.
+function timerOver () {
+  console.info('The timer is over. myVariable is: ' + myVariable);
+}
+
+var myVariable = 'Hello world!';
+
+// Create the Timer.
+var myTimer = actions.ScriptExecution.createTimerWithArgument('My Timer', now.plusSeconds(10), myVariable, timerOver);
+
+myVariable = 'Hello mutation!';
+```
+
+You may also pass `this` to the timer to have access to all variables from the current context.
+
 #### Semantics Actions
 
 See [openhab-js : actions.Semantics](https://openhab.github.io/openhab-js/actions.html#.Semantics) for complete documentation.

actions.js

@@ -199,6 +199,7 @@ const Ping = Java.type('org.openhab.core.model.script.actions.Ping');
  * ScriptExecution.createTimer​(ZonedDateTime instant, callbackFunction)
  * ScriptExecution.createTimer​(String identifier, ZonedDateTime instant, callbackFunction)
  * ScriptExecution.createTimerWithArgument​(ZonedDateTime instant, Object arg1, callbackFunction)
+ * ScriptExecution.createTimerWithArgument​(String identifier, ZonedDateTime instant, Object arg1, callbackFunction)
  *
  * @name ScriptExecution
  * @memberof actions