[items] Improve JSDoc and README for ItemPersistence#persist (#338)

Closes #335.

Signed-off-by: Florian Hotze <[email protected]>

README.md

@@ -520,14 +520,15 @@ Calling `Item.persistence` returns an `ItemPersistence` object with the followin
   - .getAllStatesBetween(begin, end, serviceId)  ⇒ `Array[PersistedItem]`
   - .lastUpdate(serviceId) ⇒ `ZonedDateTime | null`
   - .nextUpdate(serviceId)  ⇒ `ZonedDateTime | null`
-  - .maximumSince(timestamp,serviceId) ⇒ `PersistedItem | null`
-  - .maximumUntil(timestamp,serviceId) ⇒ `PersistedItem | null`
+  - .maximumSince(timestamp, serviceId) ⇒ `PersistedItem | null`
+  - .maximumUntil(timestamp, serviceId) ⇒ `PersistedItem | null`
   - .maximumBetween(begin, end, serviceId) ⇒ `PersistedItem | null`
   - .minimumSince(timestamp, serviceId) ⇒ `PersistedItem | null`
   - .minimumUntil(timestamp, serviceId) ⇒ `PersistedItem | null`
   - .minimumBetween(begin, end, serviceId) ⇒ `PersistedItem | null`
   - .persist(serviceId): Tells the persistence service to store the current Item state, which is then done asynchronously.
     **Warning:** This has the side effect, that if the Item state changes shortly after `.persist` has been called, the new Item state will be persisted. See [JSDoc](https://openhab.github.io/openhab-js/items.ItemPersistence.html#persist) for a possible work-around.
+  - .persist(timestamp, state, serviceId): Tells the persistence service to store the given state at the given timestamp, which is then done asynchronously.
   - .persistedState(timestamp, serviceId) ⇒ `PersistedItem | null`
   - .previousState(skipEqual, serviceId) ⇒ `PersistedItem | null`
   - .nextState(skipEqual, serviceId) ⇒ `PersistedItem | null`

src/items/item-persistence.js

@@ -137,13 +137,25 @@ class ItemPersistence {
   /**
    * Persists the state of a given Item.
    *
-   * Tells the persistence service to store the current state of the Item, which is then performed asynchronously.
-   * This has the side effect, that if the Item state changes shortly after `.persist` has been called, the new state will be persisted.
+   * There are four ways to use this method:
+   * ```js
+   * // Tell persistence to store the current Item state
+   * items.MyItem.persistence.persist();
+   * items.MyItem.persistence.persist('influxdb'); // using the InfluxDB persistence service
+   *
+   * // Tell persistence to store the state 'ON' at 2021-01-01 00:00:00
+   * items.MyItem.persistence.persist(time.toZDT('2021-01-01T00:00:00'), 'ON');
+   * items.MyItem.persistence.persist(time.toZDT('2021-01-01T00:00:00'), 'ON', 'influxdb'); // using the InfluxDB persistence service
+   * ```
+   *
+   * **Note:** The persistence service will store the state asynchronously in the background, this method will return immediately.
+   * When storing the current state, this has the side effect, that if the Item state changes shortly the method call, the new state will be persisted.
    * To work around that side effect, you might add `java.lang.Thread.sleep` to your code:
-   * @example
+   * ```js
    * items.MyItem.persistence.persist(); // Tell persistence to store the current Item state
    * java.lang.Thread.sleep(100); // Wait 100 ms to make sure persistence has enough time to store the current Item state
    * items.MyItem.postUpdate(0); // Now set the Item state to a new value
+   * ```
    *
    * @param {(time.ZonedDateTime | Date)} [timestamp] the date for the item state to be stored
    * @param {string} [state] the state to be stored

types/items/item-persistence.d.ts

@@ -17,13 +17,25 @@ declare class ItemPersistence {
     /**
      * Persists the state of a given Item.
      *
-     * Tells the persistence service to store the current state of the Item, which is then performed asynchronously.
-     * This has the side effect, that if the Item state changes shortly after `.persist` has been called, the new state will be persisted.
+     * There are four ways to use this method:
+     * ```js
+     * // Tell persistence to store the current Item state
+     * items.MyItem.persistence.persist();
+     * items.MyItem.persistence.persist('influxdb'); // using the InfluxDB persistence service
+     *
+     * // Tell persistence to store the state 'ON' at 2021-01-01 00:00:00
+     * items.MyItem.persistence.persist(time.toZDT('2021-01-01T00:00:00'), 'ON');
+     * items.MyItem.persistence.persist(time.toZDT('2021-01-01T00:00:00'), 'ON', 'influxdb'); // using the InfluxDB persistence service
+     * ```
+     *
+     * **Note:** The persistence service will store the state asynchronously in the background, this method will return immediately.
+     * When storing the current state, this has the side effect, that if the Item state changes shortly the method call, the new state will be persisted.
      * To work around that side effect, you might add `java.lang.Thread.sleep` to your code:
-     * @example
+     * ```js
      * items.MyItem.persistence.persist(); // Tell persistence to store the current Item state
      * java.lang.Thread.sleep(100); // Wait 100 ms to make sure persistence has enough time to store the current Item state
      * items.MyItem.postUpdate(0); // Now set the Item state to a new value
+     * ```
      *
      * @param {(time.ZonedDateTime | Date)} [timestamp] the date for the item state to be stored
      * @param {string} [state] the state to be stored