Thing actions: Clarify use of ActionOutputs annotation

[florian-h05]

The current docs are wrong,
see https://github.com/openhab/openhab-core/blob/a22349abf4b3106ec8a3eb9d36799e334cdfbf25/bundles/org.openhab.core.automation/src/main/java/org/openhab/core/automation/module/provider/AnnotationActionModuleTypeHelper.java#L146-L159 for core implementation.

[netlify]

✅ Thanks for your pull request to the openHAB documentation! The result can be previewed at the URL below (this comment and the preview will be updated if you add more commits).

Name	Link
🔨 Latest commit	b550cdb
🔍 Latest deploy log	https://app.netlify.com/sites/openhab-docs-preview/deploys/6717c1be8cccbf0008bbadc4
😎 Deploy Preview	https://deploy-preview-2388--openhab-docs-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[florian-h05]

If the current docs are correct except from the above mistake, one only needs to annotate @ActionOutput inside the @ActionOutputs annotation if the action returns a Map<String, Object>.
If there is only a single return value, no annotation is required and it won't be processed by core, as core is looking for @ActionInputs.
If a method returns such a Map, the @ActionOutputs annotation is needed.

For add-ons, this means:

1. we can remove @ActionOutput from all action returning only a single value
2. we need to add @ActionOutputs around the @ActionOutputs of all actions returning Map<String, Object>

At the moment, 2. affects not many actions:

cat **.java | grep @ActionOutput | grep "Map<String, Object>"
    public @ActionOutput(name = NEW_SCENE_ID_OUTPUT, type = "java.lang.Integer") Map<String, Object> createScene(
    public @ActionOutput(name = "result", type = "java.util.Map<String, Object>") Map<String, Object> calculateCheapestPeriod(
    public @ActionOutput(name = "result", type = "java.util.Map<String, Object>") Map<String, Object> calculateCheapestPeriod(
    public @ActionOutput(name = "result", type = "java.util.Map<String, Object>") Map<String, Object> calculateCheapestPeriod(
    public @ActionOutput(name = "result", type = "java.util.Map<String, Object>") Map<String, Object> calculateCheapestPeriod(
    public @ActionOutput(name = "errorMessages", type = "java.util.List<String>") @ActionOutput(name = "warningMessages", type = "java.util.List<String>") @ActionOutput(name = "infoMessages", type = "java.util.List<String>") @ActionOutput(name = "statusMessages", type = "java.util.List<String>") Map<String, Object> getMessages() {
    public @ActionOutput(name = "success", type = "java.lang.Boolean") @ActionOutput(name = "responseMessages", type = "java.util.List<String>") Map<String, Object> sendMessageWithResponse(
    public @ActionOutput(name = "index", type = "java.lang.Integer", label = "@text/actionOutputIndexLabel", description = "@text/actionOutputIndexDesc") @ActionOutput(name = "prev_index", type = "java.lang.Integer", label = "@text/actionOutputPrevIndexLabel", description = "@text/actionOutputPrevIndexDesc") @ActionOutput(name = "timestamp", type = "java.time.ZonedDateTime", label = "@text/actionOutputTimestampLabel", description = "@text/actionOutputTimestampDesc") @ActionOutput(name = "description", type = "java.lang.String", label = "@text/actionOutputDescriptionLabel", description = "@text/actionOutputDescriptionDesc") @ActionOutput(name = "details", type = "java.lang.String", label = "@text/actionOutputDetailsLabel", description = "@text/actionOutputDetailsDesc") Map<String, Object> readEvent(

[florian-h05]

To mention:

• It is not possible to have several actions with same method name.