Improve javadoc for all addons (#15667)

Signed-off-by: Holger Friedrich <mail@holger-friedrich.de>

bundles/org.openhab.binding.bticinosmarther/src/main/java/org/openhab/binding/bticinosmarther/internal/account/SmartherAccountHandler.java

@@ -82,8 +82,7 @@ public interface SmartherAccountHandler extends ThingHandler {
      *
      * @return the list of registered subscriptions, or an empty {@link List} in case of no subscriptions found
      *
-     * @throws {@link SmartherGatewayException}
-     *             in case of communication issues with the Smarther API
+     * @throws SmartherGatewayException in case of communication issues with the Smarther API
      */
     List<Subscription> getSubscriptions() throws SmartherGatewayException;
 
@@ -97,8 +96,7 @@ public interface SmartherAccountHandler extends ThingHandler {
      *
      * @return the identifier this subscription has been registered under
      *
-     * @throws {@link SmartherGatewayException}
-     *             in case of communication issues with the Smarther API
+     * @throws SmartherGatewayException in case of communication issues with the Smarther API
      */
     String subscribePlant(String plantId, String notificationUrl) throws SmartherGatewayException;
 
@@ -110,10 +108,7 @@ public interface SmartherAccountHandler extends ThingHandler {
      * @param subscriptionId
      *            the identifier of the subscription to be removed for the given plant
      *
-     * @return {@code true} if the plant is successfully unsubscribed, {@code false} otherwise
-     *
-     * @throws {@link SmartherGatewayException}
-     *             in case of communication issues with the Smarther API
+     * @throws SmartherGatewayException in case of communication issues with the Smarther API
      */
     void unsubscribePlant(String plantId, String subscriptionId) throws SmartherGatewayException;
 
@@ -138,21 +133,19 @@ public interface SmartherAccountHandler extends ThingHandler {
      *
      * @return the current status of the chronothermostat module
      *
-     * @throws {@link SmartherGatewayException}
-     *             in case of communication issues with the Smarther API
+     * @throws SmartherGatewayException in case of communication issues with the Smarther API
      */
     ModuleStatus getModuleStatus(String plantId, String moduleId) throws SmartherGatewayException;
 
     /**
      * Sends new settings to be applied to a given chronothermostat module.
      *
-     * @param settings
+     * @param moduleSettings
      *            the module settings to be applied
      *
      * @return {@code true} if the settings have been successfully applied, {@code false} otherwise
      *
-     * @throws {@link SmartherGatewayException}
-     *             in case of communication issues with the Smarther API
+     * @throws SmartherGatewayException in case of communication issues with the Smarther API
      */
     boolean setModuleStatus(ModuleSettings moduleSettings) throws SmartherGatewayException;
 
@@ -166,8 +159,7 @@ public interface SmartherAccountHandler extends ThingHandler {
      *
      * @return the list of registered programs, or an empty {@link List} in case of no programs found
      *
-     * @throws {@link SmartherGatewayException}
-     *             in case of communication issues with the Smarther API
+     * @throws SmartherGatewayException in case of communication issues with the Smarther API
      */
     List<Program> getModulePrograms(String plantId, String moduleId) throws SmartherGatewayException;
 

bundles/org.openhab.binding.bticinosmarther/src/main/java/org/openhab/binding/bticinosmarther/internal/account/SmartherAccountService.java

@@ -163,8 +163,8 @@ public class SmartherAccountService {
      *
      * @return a string containing the name of the authorized BTicino/Legrand portal user
      *
-     * @throws {@link SmartherGatewayException}
-     *             in case of communication issues with the Smarther API or no account handler found
+     * @throws SmartherGatewayException in case of communication issues with the Smarther API or no account handler
+     *             found
      */
     public String dispatchAuthorization(String servletBaseURL, String state, String code)
             throws SmartherGatewayException {
@@ -191,8 +191,8 @@ public class SmartherAccountService {
      * @param notification
      *            the received notification to handle
      *
-     * @throws {@link SmartherGatewayException}
-     *             in case of communication issues with the Smarther API or no notification handler found
+     * @throws SmartherGatewayException in case of communication issues with the Smarther API or no notification handler
+     *             found
      */
     public void dispatchNotification(Notification notification) throws SmartherGatewayException {
         final Sender sender = notification.getSender();

bundles/org.openhab.binding.bticinosmarther/src/main/java/org/openhab/binding/bticinosmarther/internal/account/SmartherNotificationHandler.java

@@ -39,8 +39,7 @@ public interface SmartherNotificationHandler extends ThingHandler {
      * @param plantId
      *            the identifier of the plant the notification endpoint belongs to
      *
-     * @throws {@link SmartherGatewayException}
-     *             in case of communication issues with the Smarther API
+     * @throws SmartherGatewayException in case of communication issues with the Smarther API
      */
     void registerNotification(String plantId) throws SmartherGatewayException;
 
@@ -58,8 +57,7 @@ public interface SmartherNotificationHandler extends ThingHandler {
      * @param plantId
      *            the identifier of the plant the notification endpoint belongs to
      *
-     * @throws {@link SmartherGatewayException}
-     *             in case of communication issues with the Smarther API
+     * @throws SmartherGatewayException in case of communication issues with the Smarther API
      */
     void unregisterNotification(String plantId) throws SmartherGatewayException;
 }

bundles/org.openhab.binding.bticinosmarther/src/main/java/org/openhab/binding/bticinosmarther/internal/api/SmartherApi.java

@@ -125,8 +125,7 @@ public class SmartherApi {
      *
      * @return the list of registered plants, or an empty {@link List} in case of no plants found
      *
-     * @throws {@link SmartherGatewayException}
-     *             in case of communication issues with the API gateway
+     * @throws SmartherGatewayException in case of communication issues with the API gateway
      */
     public List<Plant> getPlants() throws SmartherGatewayException {
         try {
@@ -149,8 +148,7 @@ public class SmartherApi {
      *
      * @return the list of registered modules, or an empty {@link List} in case the plant contains no module
      *
-     * @throws {@link SmartherGatewayException}
-     *             in case of communication issues with the API gateway
+     * @throws SmartherGatewayException in case of communication issues with the API gateway
      */
     public List<Module> getPlantModules(String plantId) throws SmartherGatewayException {
         try {
@@ -172,8 +170,7 @@ public class SmartherApi {
      *
      * @return the current status of the chronothermostat module
      *
-     * @throws {@link SmartherGatewayException}
-     *             in case of communication issues with the API gateway
+     * @throws SmartherGatewayException in case of communication issues with the API gateway
      */
     public ModuleStatus getModuleStatus(String plantId, String moduleId) throws SmartherGatewayException {
         try {
@@ -194,8 +191,7 @@ public class SmartherApi {
      *
      * @return {@code true} if the settings have been successfully applied, {@code false} otherwise
      *
-     * @throws {@link SmartherGatewayException}
-     *             in case of communication issues with the API gateway
+     * @throws SmartherGatewayException in case of communication issues with the API gateway
      */
     public boolean setModuleStatus(ModuleSettings settings) throws SmartherGatewayException {
         // Prepare request payload
@@ -252,8 +248,7 @@ public class SmartherApi {
      *
      * @return the list of registered programs, or an empty {@link List} in case of no programs found
      *
-     * @throws {@link SmartherGatewayException}
-     *             in case of communication issues with the API gateway
+     * @throws SmartherGatewayException in case of communication issues with the API gateway
      */
     public List<Program> getModulePrograms(String plantId, String moduleId) throws SmartherGatewayException {
         try {
@@ -274,8 +269,7 @@ public class SmartherApi {
      *
      * @return the list of registered subscriptions, or an empty {@link List} in case of no subscriptions found
      *
-     * @throws {@link SmartherGatewayException}
-     *             in case of communication issues with the API gateway
+     * @throws SmartherGatewayException in case of communication issues with the API gateway
      */
     public List<Subscription> getSubscriptions() throws SmartherGatewayException {
         try {
@@ -306,8 +300,7 @@ public class SmartherApi {
      *
      * @return the identifier this subscription has been registered under
      *
-     * @throws {@link SmartherGatewayException}
-     *             in case of communication issues with the API gateway
+     * @throws SmartherGatewayException in case of communication issues with the API gateway
      */
     public String subscribePlant(String plantId, String notificationUrl) throws SmartherGatewayException {
         try {
@@ -336,8 +329,7 @@ public class SmartherApi {
      *
      * @return {@code true} if the plant is successfully unsubscribed, {@code false} otherwise
      *
-     * @throws {@link SmartherGatewayException}
-     *             in case of communication issues with the API gateway
+     * @throws SmartherGatewayException in case of communication issues with the API gateway
      */
     public boolean unsubscribePlant(String plantId, String subscriptionId) throws SmartherGatewayException {
         final ContentResponse response = requestBasic(DELETE, String.format(PATH_UNSUBSCRIBE, plantId, subscriptionId));

bundles/org.openhab.binding.bticinosmarther/src/main/java/org/openhab/binding/bticinosmarther/internal/api/SmartherApiConnector.java

@@ -113,8 +113,7 @@ public class SmartherApiConnector {
      *
      * @return the raw response returned by the API gateway
      *
-     * @throws {@link SmartherGatewayException}
-     *             if the call failed due to an issue with the API gateway
+     * @throws SmartherGatewayException if the call failed due to an issue with the API gateway
      */
     public ContentResponse request(Function<HttpClient, Request> requester, String subscription, String authorization)
             throws SmartherGatewayException {

bundles/org.openhab.binding.bticinosmarther/src/main/java/org/openhab/binding/bticinosmarther/internal/api/dto/Chronothermostat.java

@@ -104,8 +104,8 @@ public class Chronothermostat {
      *
      * @return a {@link MeasureUnit} object representing the module operational temperature format
      *
-     * @throws {@link SmartherIllegalPropertyValueException}
-     *             if the measure internal raw unit cannot be mapped to any valid measure unit
+     * @throws SmartherIllegalPropertyValueException if the measure internal raw unit cannot be mapped to any valid
+     *             measure unit
      */
     public MeasureUnit getTemperatureFormatUnit() throws SmartherIllegalPropertyValueException {
         return MeasureUnit.fromValue(temperatureFormat);
@@ -125,8 +125,8 @@ public class Chronothermostat {
      *
      * @return {@code true} if the load state is active, {@code false} otherwise
      *
-     * @throws {@link SmartherIllegalPropertyValueException}
-     *             if the load state internal raw value cannot be mapped to any valid load state enum value
+     * @throws SmartherIllegalPropertyValueException if the load state internal raw value cannot be mapped to any valid
+     *             load state enum value
      */
     public boolean isActive() throws SmartherIllegalPropertyValueException {
         return LoadState.fromValue(loadState).isActive();

bundles/org.openhab.binding.bticinosmarther/src/main/java/org/openhab/binding/bticinosmarther/internal/api/dto/Enums.java

@@ -54,8 +54,7 @@ public class Enums {
          *
          * @return the enum value representing the given raw value
          *
-         * @throws {@link SmartherIllegalPropertyValueException}
-         *             if the raw value cannot be mapped to any valid enum value
+         * @throws SmartherIllegalPropertyValueException if the raw value cannot be mapped to any valid enum value
          */
         public static Function fromValue(String value) throws SmartherIllegalPropertyValueException {
             return lookup(Function.class, value);
@@ -91,8 +90,7 @@ public class Enums {
          *
          * @return the enum value representing the given raw value
          *
-         * @throws {@link SmartherIllegalPropertyValueException}
-         *             if the raw value cannot be mapped to any valid enum value
+         * @throws SmartherIllegalPropertyValueException if the raw value cannot be mapped to any valid enum value
          */
         public static Mode fromValue(String value) throws SmartherIllegalPropertyValueException {
             return lookup(Mode.class, value);
@@ -134,8 +132,7 @@ public class Enums {
          *
          * @return the enum value representing the given raw value
          *
-         * @throws {@link SmartherIllegalPropertyValueException}
-         *             if the raw value cannot be mapped to any valid enum value
+         * @throws SmartherIllegalPropertyValueException if the raw value cannot be mapped to any valid enum value
          */
         public static LoadState fromValue(String value) throws SmartherIllegalPropertyValueException {
             return lookup(LoadState.class, value);
@@ -190,8 +187,7 @@ public class Enums {
          *
          * @return the enum value representing the given raw value
          *
-         * @throws {@link SmartherIllegalPropertyValueException}
-         *             if the raw value cannot be mapped to any valid enum value
+         * @throws SmartherIllegalPropertyValueException if the raw value cannot be mapped to any valid enum value
          */
         public static MeasureUnit fromValue(String value) throws SmartherIllegalPropertyValueException {
             return lookup(MeasureUnit.class, value);
@@ -225,8 +221,7 @@ public class Enums {
          *
          * @return the enum value representing the given raw value
          *
-         * @throws {@link SmartherIllegalPropertyValueException}
-         *             if the raw value cannot be mapped to any valid enum value
+         * @throws SmartherIllegalPropertyValueException if the raw value cannot be mapped to any valid enum value
          */
         public static BoostTime fromValue(int value) throws SmartherIllegalPropertyValueException {
             return lookup(BoostTime.class, value);

bundles/org.openhab.binding.bticinosmarther/src/main/java/org/openhab/binding/bticinosmarther/internal/api/dto/Measure.java

@@ -69,8 +69,8 @@ public class Measure {
      *
      * @return a {@link MeasureUnit} object representing the measure unit
      *
-     * @throws {@link SmartherIllegalPropertyValueException}
-     *             if the measure internal raw unit cannot be mapped to any valid measure unit
+     * @throws SmartherIllegalPropertyValueException if the measure internal raw unit cannot be mapped to any valid
+     *             measure unit
      */
     public MeasureUnit getMeasureUnit() throws SmartherIllegalPropertyValueException {
         return MeasureUnit.fromValue(unit);
@@ -81,8 +81,8 @@ public class Measure {
      *
      * @return the value and measure unit
      *
-     * @throws {@link SmartherIllegalPropertyValueException}
-     *             if the measure internal raw unit cannot be mapped to any valid measure unit
+     * @throws SmartherIllegalPropertyValueException if the measure internal raw unit cannot be mapped to any valid
+     *             measure unit
      */
     public State toState() throws SmartherIllegalPropertyValueException {
         State state = UnDefType.UNDEF;

bundles/org.openhab.binding.bticinosmarther/src/main/java/org/openhab/binding/bticinosmarther/internal/api/dto/Sensor.java

@@ -54,8 +54,8 @@ public class Sensor {
      *
      * @return a {@link State} object representing the overall state of the sensor
      *
-     * @throws {@link SmartherIllegalPropertyValueException}
-     *             if the sensor internal raw state cannot be mapped to any valid value
+     * @throws SmartherIllegalPropertyValueException if the sensor internal raw state cannot be mapped to any valid
+     *             value
      */
     public State toState() throws SmartherIllegalPropertyValueException {
         final Measure measure = getMeasure(0);

bundles/org.openhab.binding.bticinosmarther/src/main/java/org/openhab/binding/bticinosmarther/internal/api/exception/SmartherNotificationException.java

@@ -39,7 +39,7 @@ public class SmartherNotificationException extends RuntimeException {
      *
      * @param message
      *            the error message returned from the API gateway
-     * @param cause
+     * @param exception
      *            the cause (a null value is permitted, and indicates that the cause is nonexistent or unknown)
      */
     public SmartherNotificationException(String message, Throwable exception) {

bundles/org.openhab.binding.bticinosmarther/src/main/java/org/openhab/binding/bticinosmarther/internal/util/DateUtil.java

@@ -42,8 +42,7 @@ public final class DateUtil {
      *
      * @return a {@link LocalDate} object containing the parsed date
      *
-     * @throws {@link DateTimeParseException}
-     *             if the string cannot be parsed to a local date
+     * @throws DateTimeParseException if the string cannot be parsed to a local date
      */
     public static LocalDate parseDate(@Nullable String str, String pattern) {
         if (str == null) {
@@ -63,8 +62,7 @@ public final class DateUtil {
      *
      * @return a {@link LocalDateTime} object containing the parsed date and time
      *
-     * @throws {@link DateTimeParseException}
-     *             if the string cannot be parsed to a local date and time
+     * @throws DateTimeParseException if the string cannot be parsed to a local date and time
      */
     public static LocalDateTime parseLocalTime(@Nullable String str, String pattern) {
         if (str == null) {
@@ -84,8 +82,7 @@ public final class DateUtil {
      *
      * @return a {@link ZonedDateTime} object containing the parsed date and time with timezone
      *
-     * @throws {@link DateTimeParseException}
-     *             if the string cannot be parsed to a date and time with timezone
+     * @throws DateTimeParseException if the string cannot be parsed to a date and time with timezone
      */
     public static ZonedDateTime parseZonedTime(@Nullable String str, String pattern) {
         if (str == null) {
@@ -119,8 +116,7 @@ public final class DateUtil {
      *
      * @return a string representing the local date and time object
      *
-     * @throws {@link DateTimeException}
-     *             if an error occurs during printing
+     * @throws DateTimeException if an error occurs during printing
      */
     public static String format(LocalDateTime date, String pattern) {
         DateTimeFormatter dtf = DateTimeFormatter.ofPattern(pattern);
@@ -137,8 +133,7 @@ public final class DateUtil {
      *
      * @return a string representing the date and time with timezone object
      *
-     * @throws {@link DateTimeException}
-     *             if an error occurs during printing
+     * @throws DateTimeException if an error occurs during printing
      */
     public static String format(ZonedDateTime date, String pattern) {
         DateTimeFormatter dtf = DateTimeFormatter.ofPattern(pattern);
@@ -158,8 +153,7 @@ public final class DateUtil {
      *
      * @return a string representing the range between the two local date and time objects
      *
-     * @throws {@link DateTimeException}
-     *             if an error occurs during printing
+     * @throws DateTimeException if an error occurs during printing
      */
     public static String formatRange(LocalDateTime date1, LocalDateTime date2, String pattern) {
         DateTimeFormatter dtf = DateTimeFormatter.ofPattern(pattern);
@@ -180,8 +174,7 @@ public final class DateUtil {
      *
      * @return a string representing the range between the two date and time with timezone objects
      *
-     * @throws {@link DateTimeException}
-     *             if an error occurs during printing
+     * @throws DateTimeException if an error occurs during printing
      */
     public static String formatRange(ZonedDateTime date1, ZonedDateTime date2, String pattern) {
         DateTimeFormatter dtf = DateTimeFormatter.ofPattern(pattern);

bundles/org.openhab.binding.bticinosmarther/src/main/java/org/openhab/binding/bticinosmarther/internal/util/StringUtil.java

@@ -136,8 +136,7 @@ public final class StringUtil {
      *
      * @return the string read from stream
      *
-     * @throws {@link IOException}
-     *             if an I/O error occurs
+     * @throws IOException if an I/O error occurs
      */
     public static String streamToString(InputStream input) throws IOException {
         InputStreamReader reader = new InputStreamReader(input);
@@ -162,8 +161,7 @@ public final class StringUtil {
      *
      * @return the string read from stream
      *
-     * @throws {@link IOException}
-     *             if an I/O error occurs
+     * @throws IOException if an I/O error occurs
      */
     public static String readerToString(Reader reader) throws IOException {
         final StringWriter writer = new StringWriter();