Improve ThingActions docs for UI-based rules & REST API support (#2416

)

* Improve `ThingActions` documentation for UI-based rules & REST API support

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

* Add missing BigDecimal output type

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

---------

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

developers/bindings/index.md

@@ -178,7 +178,7 @@ The following types are supported for configuration values: `Boolean`, `boolean`
 ### Properties
 
 _Things_ can have properties.
-If you would like to add meta data to your thing, e.g. the vendor of the thing, then you can define your own thing properties by simply adding them to the thing type definition.
+If you would like to add metadata to your thing, e.g. the vendor of the thing, then you can define your own thing properties by simply adding them to the thing type definition.
 The properties section [here](thing-xml.html#properties) explains how to specify such properties.
 
 To retrieve the properties one can call the operation `getProperties` of the corresponding `org.openhab.core.thing.type.ThingType` instance.
@@ -572,7 +572,8 @@ If you implement the `ThingActions` interface, you can tell the framework about
 Please note that for actions not related to Things you will instead implement an `ActionHandler` as described in the developing [Module Types](../module-types/) chapter.
 
 You start things off by implementing `ThingActions` and annotate your class with `@ThingActionsScope`.
-The scope name should be the binding name, but it can also be bindingname-xxx when you need several scopes (for different thing types).
+The scope name should be the binding name.
+There is a limitation that **only one `ThingActions` class with the same scope per thing type** is allowed, so if you need to provide several `ThingActions` classes for a single thing type, you can append a `-xxx` to the scope names.
 Since a new service is required for each thing, the component needs to be a `PROTOTYPE`:
 
 ```java
@@ -606,12 +607,15 @@ As you can see in the above `MqttActions` implementation, the framework will cal
 
 You are now free to specify as many actions as you want in `MqttActions`.
 
-In the following example we provide a "publishMQTT" action.
-An action must be annotated with `@RuleAction`, a label and a description must be provided.
+In the following example we provide a `publishMQTT` action.
+
+If an action should be available as rule action and through the REST API (and this way also through the UI), it must be annotated with `@RuleAction` and a label and a description must be provided.
 In this case we refer to translation, see [i18n](../utils/i18n.html) support, instead of directly providing a string.
+Please think about the intended use case for your action and decide based on this whether to add the `@RuleAction` annotation.
+For example actions returning a list of future prices are very practical in automation languages, but not so much in the UI.
 
 ```java
-@RuleAction(label = "@text/actionLabel", description = "@text/actionDesc")
+    @RuleAction(label = "@text/actionLabel", description = "@text/actionDesc")
     public void publishMQTT(
             @ActionInput(name = "topic", label = "@text/actionInputTopicLabel", description = "@text/actionInputTopicDesc") @Nullable String topic,
             @ActionInput(name = "value", label = "@text/actionInputValueLabel", description = "@text/actionInputValueDesc") @Nullable String value) {
@@ -630,9 +634,43 @@ In this case we refer to translation, see [i18n](../utils/i18n.html) support, in
 Each member method also requires a static method with the same name.
 This is to support the old DSL rules engine and make the action available there.
 
-Each parameter of an action member method must be annotated with `@ActionInput`.
-
-If you return values, you do so by returning a `Map<String,Object>` and annotate the method itself with as many `@ActionOutput`s as you will return map entries.
+If an action method is annotated with `@RuleAction`, each parameter of it must be annotated with `@ActionInput`.
+As action inputs can only be provided in serialised form by rule actions and through the REST API, only a limited set of input types are supported for those.
+If an action method has input parameters that have an unsupported type, the action cannot be used as a rule action (in UI-based rules) or invoked from the REST API.
+It can however still be invoked from automation languages.
+The supported input types are (see [`ActionInputHelper`](https://github.com/openhab/openhab-core/blob/main/bundles/org.openhab.core.automation/src/main/java/org/openhab/core/automation/util/ActionInputsHelper.java) for more details):
+
+- all primitive types, e.g. `boolean`, `int`, `float`, `String`, and their boxed counterparts
+- `org.openhab.core.library.types.DecimalType`
+- `org.openhab.core.library.types.QuantityType`
+- `java.time.LocalDate`
+- `java.time.LocalTime`
+- `java.time.LocalDateTime`
+- `java.util.Date`
+- `java.time.ZonedDateTime`
+- `java.time.Instant`
+- `java.time.Duration`
+
+If an action method is annotated with `@RuleAction` and it returns a value, its return value needs to be annotated.
+Depending on the return type, either `@ActionOutput` or `@ActionOutputs` needs to be used.
+If you return a single value, add the `@ActionOutput` annotation.
+If you return multiple values, you do so by returning a `Map<String, Object>` and adding the `@ActionOutputs` annotation.
+Please note that it of course is still possible to return a `Map<?, Object>`, e.g. a `Map<Instant, Object>` for a collection of values with timestamps, but this return value cannot be used by rule actions (in UI-based rules) or the REST API.
+
+As the return value needs to be serialised to be sent over the REST API, only a limited set of output types are supported by the REST API.
+If an action method has a return value that has an unsupported type, the action's return value cannot be used by rule actions (in UI-based rules) or the REST API.
+The return value can still be used in automation languages.
+The supported output types are (see [`AnnotationActionHandler`](https://github.com/openhab/openhab-core/blob/main/bundles/org.openhab.core.automation/src/main/java/org/openhab/core/automation/internal/module/handler/AnnotationActionHandler.java)):
+
+- all primitive types, e.g. `boolean`, `int`, `float`, `String`, and their boxed counterparts
+- `org.openhab.core.library.types.QuantityType`
+- `java.math.BigDecimal`
+- `java.time.LocalDate`
+- `java.time.LocalTime`
+- `java.time.LocalDateTime`
+- `java.time.ZonedDateTime`
+- `java.time.Instant`
+- `java.time.Duration`
 
 ## Firmware information / Firmware update