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 <florianh_dev@icloud.com>

* Add missing BigDecimal output type

Signed-off-by: Florian Hotze <dev@florianhotze.com>

---------

Signed-off-by: Florian Hotze <florianh_dev@icloud.com>
Signed-off-by: Florian Hotze <dev@florianhotze.com>

developers/bindings/index.md

@@ -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,9 +607,12 @@ 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.
+In the following example we provide a `publishMQTT` action.
-An action must be annotated with `@RuleAction`, a label and a description must be provided.
+
+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")
@@ -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 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):
 
-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.
+- 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