[argoclima] Post-review corrections: javadoc, etc.

Signed-off-by: Mateusz Bronk <[email protected]>

bundles/org.openhab.binding.argoclima/src/main/java/org/openhab/binding/argoclima/internal/ArgoClimaBindingConstants.java

@@ -138,8 +138,8 @@ public class ArgoClimaBindingConstants {
      * Aka. the optimistic time when the device "should acknowledge. Should be greater than
      * {@link #POLL_FREQUENCY_AFTER_COMMAND_SENT_LOCAL}
      *
-     * @see {@link #SEND_COMMAND_MAX_WAIT_TIME_LOCAL_DIRECT}
-     * @see {@link #SEND_COMMAND_MAX_WAIT_TIME_LOCAL_INDIRECT}
+     * @see #SEND_COMMAND_MAX_WAIT_TIME_LOCAL_DIRECT
+     * @see #SEND_COMMAND_MAX_WAIT_TIME_LOCAL_INDIRECT
      */
     public static final Duration SEND_COMMAND_RETRY_FREQUENCY_LOCAL = Duration.ofSeconds(10);
 
@@ -148,16 +148,17 @@ public class ArgoClimaBindingConstants {
      * Aka. the optimistic time when the server "should acknowledge. Should be greater than
      * {@link #POLL_FREQUENCY_AFTER_COMMAND_SENT_REMOTE}
      *
-     * @see {@link #SEND_COMMAND_MAX_WAIT_TIME_REMOTE}
+     * @see #SEND_COMMAND_MAX_WAIT_TIME_REMOTE
      */
     public static final Duration SEND_COMMAND_RETRY_FREQUENCY_REMOTE = Duration.ofSeconds(20);
 
     /**
      * Max time to wait for a pending command to be confirmed by the device in a local-direct mode (when we are issuing
      * communications to a device in local LAN).
      * <p>
-     * During this time, the commands may get {@link SEND_COMMAND_RETRY_FREQUENCY retried} and the device status may be
-     * {@link POLL_FREQUENCY_AFTER_COMMAND_SENT re-fetched}
+     * During this time, the commands may get {@link #SEND_COMMAND_RETRY_FREQUENCY_LOCAL retried} and the device status
+     * may be
+     * {@link #POLL_FREQUENCY_AFTER_COMMAND_SENT_LOCAL re-fetched}
      */
     public static final Duration SEND_COMMAND_MAX_WAIT_TIME_LOCAL_DIRECT = Duration.ofSeconds(20); // 60-remote
 
@@ -201,7 +202,7 @@ public class ArgoClimaBindingConstants {
     /////////////
     /**
      * Whether the binding shall wait for the device confirming commands have been received (by flipping to the desired
-     * state) or work in a fire&forget mode and stop tracking upon first send.
+     * state) or work in a fire and forget mode and stop tracking upon first send.
      * <p>
      * This applies only to confirmable commands (read-write) and is a default behavior of Argo's own web implementation
      *

bundles/org.openhab.binding.argoclima/src/main/java/org/openhab/binding/argoclima/internal/ArgoClimaConfigProvider.java

@@ -120,7 +120,7 @@ public Collection<ConfigDescription> getConfigDescriptions(@Nullable Locale loca
     @Override
     @Nullable
     public ConfigDescription getConfigDescription(URI uri, @Nullable Locale locale) {
-        if (!uri.getScheme().equalsIgnoreCase("thing")) {
+        if (!"thing".equalsIgnoreCase(uri.getScheme())) {
             return null; // Deliberately not supporting "thing-type" (no dynamic parameters there)
         }
         ThingUID thingUID = new ThingUID(Objects.requireNonNull(uri.getSchemeSpecificPart()));
@@ -211,8 +211,6 @@ public ConfigDescription getConfigDescription(URI uri, @Nullable Locale locale)
                     .withDefault("false").withVerify(true).build()));
         }
 
-        var config = ConfigDescriptionBuilder.create(uri).withParameterGroups(paramGroups).withParameters(parameters)
-                .build();
-        return config;
+        return ConfigDescriptionBuilder.create(uri).withParameterGroups(paramGroups).withParameters(parameters).build();
     }
 }

bundles/org.openhab.binding.argoclima/src/main/java/org/openhab/binding/argoclima/internal/configuration/ArgoClimaConfigurationBase.java

@@ -130,8 +130,8 @@ public int getRefreshInterval() {
      *
      * @implNote While this is configured by its dedicated settings (for better UX) and valid only for Local Thing
      *           types, internal implementation uses {@code refreshInterval == 0} to signify no comms. This is because
-     *           without a refresh, the binding would have to function in a fire&forget mode sending commands back to
-     *           HVAC and never receiving any ACK... which makes little sense, hence is not supported
+     *           without a refresh, the binding would have to function in a fire and forget mode sending commands back
+     *           to HVAC and never receiving any ACK... which makes little sense, hence is not supported
      *
      * @return True if the Thing is allowed to communicate outwards on its own, False otherwise
      */

bundles/org.openhab.binding.argoclima/src/main/java/org/openhab/binding/argoclima/internal/configuration/ArgoClimaConfigurationLocal.java

@@ -32,13 +32,13 @@
  */
 @NonNullByDefault
 public class ArgoClimaConfigurationLocal extends ArgoClimaConfigurationBase {
-    public static enum ConnectionMode {
+    public enum ConnectionMode {
         LOCAL_CONNECTION,
         REMOTE_API_STUB,
         REMOTE_API_PROXY
     }
 
-    public static enum DeviceSidePasswordDisplayMode {
+    public enum DeviceSidePasswordDisplayMode {
         NEVER,
         MASKED,
         CLEARTEXT

bundles/org.openhab.binding.argoclima/src/main/java/org/openhab/binding/argoclima/internal/configuration/IScheduleConfigurationProvider.java

@@ -41,7 +41,7 @@ public interface IScheduleConfigurationProvider {
      *
      * @author Mateusz Bronk - Initial contribution
      */
-    public static enum ScheduleTimerType {
+    public enum ScheduleTimerType {
         SCHEDULE_1,
         SCHEDULE_2,
         SCHEDULE_3;

bundles/org.openhab.binding.argoclima/src/main/java/org/openhab/binding/argoclima/internal/device/api/ArgoClimaRemoteDevice.java

@@ -43,7 +43,7 @@
  * actual vendor's servers)
  *
  * <p>
- * Use of this mode is actually NOT recommended for advanced users as cleartext device & Wi-Fi passwords are sent to
+ * Use of this mode is actually NOT recommended for advanced users as cleartext device and Wi-Fi passwords are sent to
  * Argo servers through unencrypted HTTP connection (sic!). If the Argo UI access is desired (ex. for FW update or IR
  * remote-like experience), consider using this mode only on a dedicated Wi-Fi network (and possibly through VPN)
  *

bundles/org.openhab.binding.argoclima/src/main/java/org/openhab/binding/argoclima/internal/device/api/protocol/ArgoApiDataElement.java

@@ -196,8 +196,8 @@ public State getState() {
      *
      * @param command The command to handle
      * @return Status on whether the command has been handled (accepted). Note "handled" here doesn't mean
-     *         sent&confirmed by the device, merely recognized by the framework and accepted for subsequent device-side
-     *         communication (which happens asynchronously to this call)
+     *         sent and confirmed by the device, merely recognized by the framework and accepted for subsequent
+     *         device-side communication (which happens asynchronously to this call)
      */
     public boolean handleCommand(Command command) {
         if (this.type != DataElementType.WRITE_ONLY && this.type != DataElementType.READ_WRITE) {

bundles/org.openhab.binding.argoclima/src/main/java/org/openhab/binding/argoclima/internal/device/api/protocol/elements/ArgoApiElementBase.java

@@ -97,7 +97,7 @@ public static HandleCommandResult accepted(String deviceCommandToSend, State pla
 
         /**
          * Check if this command is stale (has been issued before
-         * {@link ArgoClimaBindingConstants.PENDING_COMMAND_EXPIRE_TIME} ago.
+         * {@link ArgoClimaBindingConstants#PENDING_COMMAND_EXPIRE_TIME} ago.
          *
          * @implNote This class does NOT track actual command completion (only their issuance), hence it is expected
          *           that a completed command will be simply removed by the caller.
@@ -147,7 +147,7 @@ public boolean isDeferred() {
         /**
          * Set deferred status (update from default: false)
          *
-         * @see {@link #isDeferred()}
+         * @see #isDeferred()
          * @param deferred New {@code deferred} value
          * @return This object (for chaining)
          */
@@ -177,7 +177,7 @@ public enum CommandFinalizationReason {
         ABORTED,
         /**
          * Pending (confirmable) command has not received confirmation within
-         * {@link ArgoClimaBindingConstants.PENDING_COMMAND_EXPIRE_TIME}
+         * {@link ArgoClimaBindingConstants#PENDING_COMMAND_EXPIRE_TIME}
          */
         EXPIRED
     }

bundles/org.openhab.binding.argoclima/src/main/java/org/openhab/binding/argoclima/internal/device/api/protocol/elements/EnumParam.java

@@ -57,7 +57,7 @@ public EnumParam(IArgoSettingProvider settingsProvider, Class<E> cls) {
     /**
      * Gets the raw enum value from {@link Type} ({@link Command} or {@link State}) which are themselves strings
      *
-     * @see {@link #valueToState(Optional)} for a reverse conversion
+     * @see #valueToState(Optional) for a reverse conversion
      *
      * @param <E> The type of underlying enum - implementing {@link IArgoApiEnum}
      * @param value Value to convert

bundles/org.openhab.binding.argoclima/src/main/java/org/openhab/binding/argoclima/internal/device/api/protocol/elements/IArgoCommandableElement.java

@@ -20,7 +20,7 @@
  * Interface for Argo API parameter (individual HMI element)
  * Carries high-level command-management options
  *
- * @see {@link IArgoElement}
+ * @see IArgoElement
  *
  * @author Mateusz Bronk - Initial contribution
  */
@@ -39,8 +39,9 @@ interface IArgoElement extends IArgoCommandableElement {
         /**
          * Returns the raw Argo command to be sent to the device (if update is pending)
          *
-         * @return Command to send to device (if update pending), or {@link ArgoApiElementBase#NO_VALUE NO_VALUE} -
-         *         otherwise
+         * @return Command to send to device (if update pending), or
+         *         {@link org.openhab.binding.argoclima.internal.device.api.protocol.ArgoDeviceStatus#NO_VALUE NO_VALUE}
+         *         - otherwise
          */
         public String getDeviceApiValue();
 
@@ -92,7 +93,7 @@ interface IArgoElement extends IArgoCommandableElement {
      * Notify that the withstanding command has just been sent to the device (and is now pending device-side
      * confirmation - if confirmable)
      *
-     * @note Used for write-only params, to indicate they have been (hopefully) correctly sent to the device
+     * @implNote Used for write-only params, to indicate they have been (hopefully) correctly sent to the device
      */
     public void notifyCommandSent();
 

bundles/org.openhab.binding.argoclima/src/main/java/org/openhab/binding/argoclima/internal/device/api/protocol/elements/TimeParam.java

@@ -31,7 +31,8 @@
 /**
  * Time element (accepting values in HH:MM) - eg. for schedule timers on/off
  *
- * @see {@link CurrentTimeParam}, {@link DelayMinutesParam}
+ * @see CurrentTimeParam
+ * @see DelayMinutesParam
  * @implNote These other "time" params could technically be sharing common codebase, though for simplicity sake it was
  *           easier to implement them as unrelated (possible future refactor oppty)
  *
@@ -45,7 +46,7 @@ public class TimeParam extends ArgoApiElementBase {
     /**
      * Kind of schedule parameter (on or off)
      */
-    public static enum TimeParamType {
+    public enum TimeParamType {
         ON,
         OFF
     }
@@ -57,7 +58,7 @@ public static enum TimeParamType {
     private Optional<Integer> currentValue = Optional.empty();
 
     /**
-     * C-tor (allows full range of values: 0:00 <> 25:59)
+     * C-tor (allows full range of values: {@code 0:00 <> 25:59})
      *
      * @implNote Even though the Argo HVAC supports 3 schedule timers, when sent to a device, there's only one
      *           on/off/weekday option, hence value of this setting changes indirectly (when changing Schedule timer

bundles/org.openhab.binding.argoclima/src/main/java/org/openhab/binding/argoclima/internal/device/api/protocol/elements/WeekdayParam.java

@@ -32,7 +32,7 @@
 /**
  * Weekdays element (accepting sets of days for schedule to run on)
  *
- * @see {@link TimeParam}
+ * @see TimeParam
  * @author Mateusz Bronk - Initial contribution
  */
 @NonNullByDefault

bundles/org.openhab.binding.argoclima/src/main/java/org/openhab/binding/argoclima/internal/device/api/types/TimerType.java

@@ -21,7 +21,7 @@
  * The device supports a "delay" timer + 3 configurable "schedule" timers. All the schedule timers share the same API
  * fields for configuring days of week when they are active as well as start/stop time
  *
- * @see {@link ScheduleTimerType} - for schedule-specific enum (used in binding configuration)
+ * @see ScheduleTimerType - for schedule-specific enum (used in binding configuration)
  * @author Mateusz Bronk - Initial contribution
  */
 @NonNullByDefault

bundles/org.openhab.binding.argoclima/src/main/java/org/openhab/binding/argoclima/internal/device/passthrough/requests/DeviceSidePostRtUpdateDTO.java

@@ -43,7 +43,7 @@ public class DeviceSidePostRtUpdateDTO {
     /** A MD5 hash of password to the remote server (and hence the UI) */
     public final String passwordHash;
 
-    /** The CPU_ID (unique & immutable HVAC identifier) send by the device */
+    /** The CPU_ID (unique and immutable HVAC identifier) send by the device */
     public final String cpuId;
 
     /** Unknown purpose, seems to be set to 1 in all requests observed. DEL is for delta? */

bundles/org.openhab.binding.argoclima/src/main/java/org/openhab/binding/argoclima/internal/exception/ArgoRemoteServerStubStartupException.java

@@ -20,8 +20,7 @@
  * The class {@code ArgoRemoteServerStubStartupException} is thrown in case of any issues when starting the stub Argo
  * server (for intercepting mode)
  *
- * @see {@link org.openhab.binding.argoclima.internal.device.passthrough.RemoteArgoApiServerStub
- *      RemoteArgoApiServerStub}
+ * @see org.openhab.binding.argoclima.internal.device.passthrough.RemoteArgoApiServerStub
  * @author Mateusz Bronk - Initial contribution
  */
 @NonNullByDefault

bundles/org.openhab.binding.argoclima/src/main/java/org/openhab/binding/argoclima/internal/handler/ArgoClimaHandlerBase.java

@@ -53,8 +53,8 @@
  * The {@code ArgoClimaHandlerBase} is an abstract base class for common logic (across local and remote thing
  * implementations) responsible for handling commands, which are sent to one of the channels.
  *
- * @see {@link ArgoClimaHandlerLocal}
- * @see {@link ArgoClimaHandlerRemote}
+ * @see ArgoClimaHandlerLocal
+ * @see ArgoClimaHandlerRemote
  *
  * @param <ConfigT> Type of configuration class used:
  *            {@link org.openhab.binding.argoclima.internal.configuration.ArgoClimaConfigurationLocal
@@ -137,7 +137,7 @@ public ArgoClimaHandlerBase(Thing thing, boolean awaitConfirmationAfterSend, Dur
      * @return Initialized Device API
      * @throws ArgoConfigurationException In case the API initialization fails due to Thing configuration issues
      * @throws ArgoRemoteServerStubStartupException In case the Device API startup involved launching an intercepting
-     *             server (thing type && configuration-dependent), and the startup has failed
+     *             server (thing type and configuration-dependent), and the startup has failed
      */
     protected abstract IArgoClimaDeviceAPI initializeDeviceApi(ConfigT config)
             throws ArgoRemoteServerStubStartupException, ArgoConfigurationException;
@@ -487,9 +487,9 @@ private final boolean handleIndividualSettingCommand(ArgoDeviceSettingType setti
      *
      * @param entries The new properties to append/replace (this does not clear existing properties!)
      *
-     * @implNote Unfortunately framework's {@link BaseThingHandler#updateProperties()} implementation clones the map
-     *           into a {@code HashMap}, which means the edited properties will lose their sorting, yet still providing
-     *           it via a {@code TreeMap} in hopes framework may respect the ordering some day ;)
+     * @implNote Unfortunately framework's {@link BaseThingHandler#updateProperties(Map<String, String>)} implementation
+     *           clones the map into a {@code HashMap}, which means the edited properties will lose their sorting, yet
+     *           still providing it via a {@code TreeMap} in hopes framework may respect the ordering some day ;)
      * @apiNote This method is also called asynchronously from an intercepting/stub server
      */
     protected final void updateThingProperties(SortedMap<String, String> entries) {

bundles/org.openhab.binding.argoclima/src/main/java/org/openhab/binding/argoclima/internal/handler/ArgoClimaHandlerLocal.java

@@ -92,7 +92,7 @@ protected ArgoClimaConfigurationLocal getConfigInternal() throws ArgoConfigurati
     /**
      * {@inheritDoc}
      * <p>
-     * For any {@code REMOTE_API_*} <b>Connection mode<b>, this starts a new HTTP server (with its own thread pool!)
+     * For any {@code REMOTE_API_*} <b>Connection mode</b>, this starts a new HTTP server (with its own thread pool!)
      * listening for HVAC connections.
      * <p>
      * Additionally for a {@code REMOTE_API_PROXY}, a custom HTTP client is also created, proxying the calls from device