Fix SAT JavadocMethodStyleCheck findings (#1109)

* Fix SAT JavadocMethodStyleCheck findings

Signed-off-by: Wouter Born <github@maindrain.net>

bundles/org.openhab.core.automation/src/main/java/org/openhab/core/automation/handler/ActionHandler.java

@@ -37,7 +37,6 @@ public interface ActionHandler extends ModuleHandler {
      *
      * @param context an unmodifiable map containing the outputs of the {@link Trigger} that triggered the {@link Rule},
      *            the outputs of all preceding {@link Action}s, and the inputs for this {@link Action}.
-     *
      * @return a map with the {@code outputs} which are the result of the {@link Action}'s execution (may be null).
      */
     @Nullable

bundles/org.openhab.core.automation/src/main/java/org/openhab/core/automation/module/provider/i18n/ModuleTypeI18nService.java

@@ -27,9 +27,9 @@ public interface ModuleTypeI18nService {
     /**
      * Builds a {@link ModuleType} with the given {@link Locale}
      *
-     * @param defModuleType - the ModuleType as defined
+     * @param defModuleType the ModuleType as defined
-     * @param locale - a Locale into which the type should be translated
+     * @param locale a Locale into which the type should be translated
-     * @param bundle - the bundle containing the localization files
+     * @param bundle the bundle containing the localization files
      * @return the localized ModuleType
      */
     ModuleType getModuleTypePerLocale(ModuleType defModuleType, Locale locale, Bundle bundle);

bundles/org.openhab.core.automation/src/main/java/org/openhab/core/automation/util/ReferenceResolver.java

@@ -309,7 +309,6 @@ public class ReferenceResolver {
      * @param tokens a sequence of field names, indexes, or keys that represent the hierarchical path to the required
      *            object
      * @return the value of the object to witch the hierarchical path is pointing.
-     *
      * @throws IllegalArgumentException if one of the tokens point to field that is not existing or the object is null
      * @throws SecurityException If a security manager, <i>s</i>, is present and any of the following
      *             conditions is met:

bundles/org.openhab.core.compat1x/src/main/java/org/openhab/core/binding/BindingProvider.java

@@ -41,7 +41,6 @@ public interface BindingProvider {
      * <code>itemName</code>
      *
      * @param itemName the itemName to check
-     *
      * @return <code>true</code> if this provider contains an adequate mapping
      *         for <code>itemName</code> and <code>false</code> otherwise.
      */

bundles/org.openhab.core.compat1x/src/main/java/org/openhab/core/items/ItemFactory.java

@@ -25,7 +25,6 @@ public interface ItemFactory {
      *
      * @param itemTypeName
      * @param itemName
-     *
      * @return a new Item of type <code>itemTypeName</code> or
      *         <code>null</code> if no matching class is known.
      */

bundles/org.openhab.core.compat1x/src/main/java/org/openhab/core/library/types/PointType.java

@@ -142,8 +142,7 @@ public class PointType implements ComplexType, Command, State {
      * (alphabetical) order of their keys.
      * </p>
      *
-     * @param pattern
+     * @param pattern the pattern to use containing indexes to reference the single
-     *            the pattern to use containing indexes to reference the single
      *            elements of this type.
      */
     @Override

bundles/org.openhab.core.compat1x/src/main/java/org/openhab/core/transform/TransformationService.java

@@ -37,10 +37,8 @@ public interface TransformationService {
      *
      * @param function the function to be used to transform the input
      * @param source the input to be transformed
-     *
      * @return the transformed result or the unchanged <code>source</code> if the
      *         transformation couldn't be completed for any reason.
-     *
      * @throws TransformationException if any error occurs
      */
     String transform(String function, String source) throws TransformationException;

bundles/org.openhab.core.compat1x/src/main/java/org/openhab/core/transform/actions/Transformation.java

@@ -35,8 +35,7 @@ public class Transformation {
      * @param type the transformation type, e.g. REGEX or MAP
      * @param function the function to call, this value depends on the transformation type
      * @param value the value to apply the transformation to
-     * @return
+     * @return the transformed value or the original one, if there was no service registered for the
-     *         the transformed value or the original one, if there was no service registered for the
      *         given type or a transformation exception occurred.
      */
     public static String transform(String type, String function, String value) {

bundles/org.openhab.core.compat1x/src/main/java/org/openhab/io/net/actions/Exec.java

@@ -40,8 +40,7 @@ public class Exec {
      * done.
      * </p>
      *
-     * @param commandLine
+     * @param commandLine the command line to execute
-     *            the command line to execute
      * @see http://www.peterfriese.de/running-applescript-from-java/
      */
     @ActionDoc(text = "Executes <code>commandLine</code>.")
@@ -63,10 +62,8 @@ public class Exec {
      * done.
      * </p>
      *
-     * @param commandLine
+     * @param commandLine the command line to execute
-     *            the command line to execute
+     * @param timeout timeout for execution in milliseconds
-     * @param timeout
-     *            timeout for execution in milliseconds
      * @return response data from executed command line
      */
     @ActionDoc(text = "Executes <code>commandLine</code>.")

bundles/org.openhab.core.compat1x/src/main/java/org/openhab/io/net/actions/Ping.java

@@ -35,11 +35,9 @@ public class Ping {
      * @param host
      * @param port
      * @param timeout
-     *
      * @return <code>true</code> when <code>host</code> is reachable on <code>port</code>
      *         within the given <code>timeout</code> and <code>false</code> in all other
      *         cases.
-     *
      * @throws IOException
      * @throws SocketTimeoutException
      */

bundles/org.openhab.core.compat1x/src/main/java/org/openhab/io/net/exec/ExecUtil.java

@@ -52,8 +52,7 @@ public class ExecUtil {
      * done.
      * </p>
      *
-     * @param commandLine
+     * @param commandLine the command line to execute
-     *            the command line to execute
      * @see http://www.peterfriese.de/running-applescript-from-java/
      */
     public static void executeCommandLine(String commandLine) {
@@ -85,10 +84,8 @@ public class ExecUtil {
      * done.
      * </p>
      *
-     * @param commandLine
+     * @param commandLine the command line to execute
-     *            the command line to execute
+     * @param timeout timeout for execution in milliseconds
-     * @param timeout
-     *            timeout for execution in milliseconds
      * @return response data from executed command line
      */
     public static String executeCommandLineAndWaitResponse(String commandLine, int timeout) {

bundles/org.openhab.core.compat1x/src/main/java/org/openhab/io/net/http/HttpUtil.java

@@ -63,7 +63,6 @@ public class HttpUtil {
      * @param httpMethod the HTTP method to use
      * @param url the url to execute (in milliseconds)
      * @param timeout the socket timeout to wait for data
-     *
      * @return the response body or <code>NULL</code> when the request went wrong
      */
     public static String executeUrl(String httpMethod, String url, int timeout) {
@@ -81,7 +80,6 @@ public class HttpUtil {
      *            <code>null</code> if no content should be send.
      * @param contentType the content type of the given <code>content</code>
      * @param timeout the socket timeout to wait for data
-     *
      * @return the response body or <code>NULL</code> when the request went wrong
      */
     public static String executeUrl(String httpMethod, String url, InputStream content, String contentType,
@@ -101,7 +99,6 @@ public class HttpUtil {
      *            <code>null</code> if no content should be send.
      * @param contentType the content type of the given <code>content</code>
      * @param timeout the socket timeout to wait for data
-     *
      * @return the response body or <code>NULL</code> when the request went wrong
      */
     public static String executeUrl(String httpMethod, String url, Properties httpHeaders, InputStream content,
@@ -221,7 +218,6 @@ public class HttpUtil {
      *
      * @param urlString
      * @param nonProxyHosts
-     *
      * @return <code>false</code> if the host of the given <code>urlString</code>
      *         is contained in <code>nonProxyHosts</code>-list and <code>true</code>
      *         otherwise
@@ -267,7 +263,6 @@ public class HttpUtil {
      * </pre>
      *
      * @param url the URL to extract {@link Credentials} from
-     *
      * @return the exracted Credentials or <code>null</code> if the given
      *         <code>url</code> does not contain credentials
      */
@@ -298,7 +293,6 @@ public class HttpUtil {
      *
      * @param httpMethodString the name of the {@link HttpMethod} to create
      * @param url
-     *
      * @return an object of type {@link GetMethod}, {@link PutMethod},
      *         {@link PostMethod} or {@link DeleteMethod}
      * @throws IllegalArgumentException if <code>httpMethod</code> is none of

bundles/org.openhab.core.compat1x/src/main/java/org/openhab/model/item/binding/BindingConfigReader.java

@@ -12,6 +12,7 @@
  */
 package org.openhab.model.item.binding;
 
+import org.eclipse.smarthome.model.item.internal.GenericItemProvider;
 import org.openhab.core.items.Item;
 
 /**
@@ -35,7 +36,6 @@ public interface BindingConfigReader {
      * @param item the item whose type is validated
      * @param bindingConfig the config string which could be used to refine the
      *            validation
-     *
      * @throws BindingConfigParseException if the type of <code>item</code> is
      *             invalid for this binding
      */
@@ -48,7 +48,6 @@ public interface BindingConfigReader {
      * @param context a string of the context from where this item comes from. Usually the file name of the config file
      * @param item the item for which the binding is defined
      * @param bindingConfig the configuration string that must be processed
-     *
      * @throws BindingConfigParseException if the configuration string is not valid
      */
     public void processBindingConfiguration(String context, Item item, String bindingConfig)

bundles/org.openhab.core.compat1x/src/main/java/org/openhab/ui/chart/ChartProvider.java

@@ -36,38 +36,21 @@ public interface ChartProvider {
      * Creates a chart object. This sets the initial parameters for the chart
      * before the items are added
      *
-     * @param service
+     * @param service A string containing the name of the persistence service. May be null in which case the chart
-     *            A string containing the name of the persistence service. May
+     *            provider can decide itself which store to use.
-     *            be null in which case the chart provider can decide itself
+     * @param widget The widget ID. This allows the chart provider to look up the widget and get the items directly from
-     *            which store to use.
+     *            the sitemap definition. May be null.
-     * @param widget
+     * @param theme A string containing a theme name for the chart. The provider should store its own themes. May be
-     *            The widget ID. This allows the chart provider to look up the
+     *            null to use a default theme.
-     *            widget and get the items directly from the sitemap definition.
+     * @param height The height of the chart.
-     *            May be null.
+     * @param width The width of the chart.
-     * @param theme
+     * @param startTime The start time of the chart
-     *            A string containing a theme name for the chart. The provider
+     * @param endTime The end time of the chart
-     *            should store its own themes. May be null to use a default
+     * @param height The height of the chart
-     *            theme.
+     * @param width The width of the chart
-     * @param height
+     * @param items The items to display on the chart
-     *            The height of the chart.
+     * @param groups The groups to display on the chart
-     * @param width
+     * @return BufferedImage object if the chart is rendered correctly, otherwise null.
-     *            The width of the chart.
-     * @param startTime
-     *            The start time of the chart
-     * @param endTime
-     *            The end time of the chart
-     * @param height
-     *            The height of the chart
-     * @param width
-     *            The width of the chart
-     * @param items
-     *            The items to display on the chart
-     * @param groups
-     *            The groups to display on the chart
-     *
-     * @return BufferedImage object if the chart is rendered correctly,
-     *         otherwise null.
-     *
      * @throws ItemNotFoundException if an item or group is not found
      * @throws IllegalArgumentException if an invalid argument is passed
      */

bundles/org.openhab.core.compat1x/src/main/java/org/openhab/ui/items/ItemUIProvider.java

@@ -50,7 +50,6 @@ public interface ItemUIProvider {
      *
      * @param itemType the class of the item
      * @param itemName the item name to get the default widget for
-     *
      * @return a widget implementation that can be used for the given item
      */
     public Widget getDefaultWidget(Class<? extends Item> itemType, String itemName);

bundles/org.openhab.core.compat1x/src/main/java/org/openhab/ui/items/ItemUIRegistry.java

@@ -40,8 +40,7 @@ public interface ItemUIRegistry extends ItemRegistry, ItemUIProvider {
      * “[%s]" for a string or "[%.3f]" for a decimal, this is replaced by the
      * current value of the item and padded by a "<span>" element.
      *
-     * @param w
+     * @param w the widget to retrieve the label for
-     *            the widget to retrieve the label for
      * @return the label to use for the widget
      */
     public String getLabel(Widget w);
@@ -58,8 +57,7 @@ public interface ItemUIRegistry extends ItemRegistry, ItemUIProvider {
      * "switch-on". If no such icon exists, the base icon ("switch") will be
      * returned nonetheless.
      *
-     * @param w
+     * @param w the widget to retrieve the icon name for
-     *            the widget to retrieve the icon name for
      * @return the icon name to use for the widget
      */
     public String getIcon(Widget w);
@@ -68,8 +66,7 @@ public interface ItemUIRegistry extends ItemRegistry, ItemUIProvider {
      * Retrieves the current state of the item of a widget or
      * <code>UnDefType.UNDEF</code>.
      *
-     * @param w
+     * @param w the widget to retrieve the item state for
-     *            the widget to retrieve the item state for
      * @return the item state of the widget
      */
     public State getState(Widget w);
@@ -77,10 +74,8 @@ public interface ItemUIRegistry extends ItemRegistry, ItemUIProvider {
     /**
      * Retrieves the widget for a given id on a given sitemap.
      *
-     * @param sitemap
+     * @param sitemap the sitemap to look for the widget
-     *            the sitemap to look for the widget
+     * @param id the id of the widget to look for
-     * @param id
-     *            the id of the widget to look for
      * @return the widget for the given id
      */
     public Widget getWidget(Sitemap sitemap, String id);
@@ -94,8 +89,7 @@ public interface ItemUIRegistry extends ItemRegistry, ItemUIProvider {
      * and not available in the sitemap, the name of its associated item is used
      * instead.
      *
-     * @param w
+     * @param w the widget to get the id for
-     *            the widget to get the id for
      * @return an id for this widget
      */
     public String getWidgetId(Widget w);
@@ -105,8 +99,7 @@ public interface ItemUIRegistry extends ItemRegistry, ItemUIProvider {
      * might be no children defined on the widget, but they should be
      * dynamically determined by looking at the members of the underlying item.
      *
-     * @param w
+     * @param w the widget to retrieve the children for
-     *            the widget to retrieve the children for
      * @return the (dynamically or statically defined) children of the widget
      */
     public EList<Widget> getChildren(LinkableWidget w);
@@ -114,8 +107,7 @@ public interface ItemUIRegistry extends ItemRegistry, ItemUIProvider {
     /**
      * Checks whether an icon with a given name exists
      *
-     * @param icon
+     * @param icon the icon name to check
-     *            the icon name to check
      * @return true, if the icon exists
      */
     public boolean iconExists(String icon);
@@ -124,8 +116,7 @@ public interface ItemUIRegistry extends ItemRegistry, ItemUIProvider {
      * Gets the label color for the widget. Checks conditional statements to
      * find the color based on the item value
      *
-     * @param w
+     * @param w Widget
-     *            Widget
      * @return String with the color
      */
     public String getLabelColor(Widget w);
@@ -134,8 +125,7 @@ public interface ItemUIRegistry extends ItemRegistry, ItemUIProvider {
      * Gets the value color for the widget. Checks conditional statements to
      * find the color based on the item value
      *
-     * @param w
+     * @param w Widget
-     *            Widget
      * @return String with the color
      */
     public String getValueColor(Widget w);
@@ -143,8 +133,7 @@ public interface ItemUIRegistry extends ItemRegistry, ItemUIProvider {
     /**
      * Gets the widget visibility based on the item state
      *
-     * @param w
+     * @param w Widget
-     *            Widget
      * @return true if the item is visible
      */
     public boolean getVisiblity(Widget w);
@@ -152,8 +141,7 @@ public interface ItemUIRegistry extends ItemRegistry, ItemUIProvider {
     /**
      * Gets the item state
      *
-     * @param itemName
+     * @param itemName item name
-     *            item name
      * @return State of the item
      */
     public State getItemState(String itemName);

bundles/org.openhab.core.test/src/main/java/org/eclipse/smarthome/test/SyntheticBundleInstaller.java

@@ -99,7 +99,6 @@ public class SyntheticBundleInstaller {
      *            for the synthetic bundle
      * @param extensionsToInclude a list of extension to be included into the synthetic bundle. In order to use the list
      *            of default extensions ({@link #DEFAULT_EXTENSIONS})
-     *
      * @return the synthetic bundle representation
      * @throws Exception thrown when error occurs while installing or starting the synthetic bundle
      */
@@ -123,7 +122,6 @@ public class SyntheticBundleInstaller {
      * @param testBundleName the symbolic name of the sub-directory of {@value #BUNDLE_POOL_PATH}, which contains the
      *            files for the synthetic bundle
      * @param extensionsToInclude a list of extension to be included into the synthetic bundle
-     *
      * @return the synthetic bundle representation
      * @throws Exception thrown when error occurs while installing or starting the synthetic bundle
      */
@@ -211,8 +209,7 @@ public class SyntheticBundleInstaller {
      *
      * @param bundleContext the bundle context of the test runtime
      * @param testBundleName the name of the sub-directory of {@value #BUNDLE_POOL_PATH}, which contains the files for
-     *            the
+     *            the synthetic bundle
-     *            synthetic bundle
      * @param extensionsToInclude a list of extension to be included into the synthetic bundle fragment. In order to use
      *            the list of default extensions ({@link #DEFAULT_EXTENSIONS})
      * @return the synthetic bundle representation
@@ -229,8 +226,7 @@ public class SyntheticBundleInstaller {
      *
      * @param bundleContext the bundle context of the test runtime
      * @param testBundleName the name of the sub-directory of {@value #BUNDLE_POOL_PATH}, which contains the files for
-     *            the
+     *            the synthetic bundle
-     *            synthetic bundle
      * @return the synthetic bundle representation
      * @throws Exception thrown when error occurs while installing or starting the synthetic bundle fragment
      */

bundles/org.openhab.core/src/main/java/org/eclipse/smarthome/core/auth/AuthenticationManager.java

@@ -26,7 +26,7 @@ public interface AuthenticationManager {
      * @param credentials Credentials to authenticate with.
      * @return Null value should never be returned. Any failed authentication (for whatever reason), should cause
      *         AuthenticationException.
-     * @throws AuthenticationException - when none of available authentication methods succeeded.
+     * @throws AuthenticationException when none of available authentication methods succeeded.
      */
     Authentication authenticate(Credentials credentials) throws AuthenticationException;
 

bundles/org.openhab.core/src/main/java/org/eclipse/smarthome/core/auth/client/oauth2/AccessTokenResponse.java

@@ -110,7 +110,6 @@ public final class AccessTokenResponse implements Serializable, Cloneable {
      * @param tokenExpiresInBuffer A positive integer in seconds to act as additional buffer to the calculation.
      *            This causes the OAuthToken to expire earlier then the stated expiry-time given
      *            by the authorization server.
-     *
      * @return true if object is not-initialized, or expired, or expired early due to buffer
      */
     public boolean isExpired(@NonNull LocalDateTime givenTime, int tokenExpiresInBuffer) {

bundles/org.openhab.core/src/main/java/org/eclipse/smarthome/core/auth/client/oauth2/StorageCipher.java

@@ -39,7 +39,7 @@ public interface StorageCipher {
      * Encrypt the plainText, then produce a base64 encoded cipher text
      *
      * @param plainText
-     * @return base64-encoded( encrypted( text ) )
+     * @return base64 encoded( encrypted( text ) )
      * @throws GeneralSecurityException all security-related exception
      */
     @Nullable

bundles/org.openhab.core/src/main/java/org/eclipse/smarthome/core/items/ItemBuilderFactory.java

@@ -26,7 +26,6 @@ public interface ItemBuilderFactory {
      * Create a new {@link ItemBuilder}, which is initialized by the given item.
      *
      * @param item the template to initialize the builder with
-     *
      * @return an ItemBuilder instance
      */
     ItemBuilder newItemBuilder(Item item);
@@ -36,7 +35,6 @@ public interface ItemBuilderFactory {
      *
      * @param itemType the item type to create
      * @param itemName the name of the item to create
-     *
      * @return an ItemBuilder instance
      */
     ItemBuilder newItemBuilder(String itemType, String itemName);

bundles/org.openhab.core/src/main/java/org/eclipse/smarthome/core/library/types/DateTimeType.java

@@ -148,7 +148,6 @@ public class DateTimeType implements PrimitiveType, State, Command {
      * Create a {@link DateTimeType} being the translation of the current object to the locale time zone
      *
      * @return a {@link DateTimeType} translated to the locale time zone
-     *
      * @throws DateTimeException if the converted zone ID has an invalid format or the result exceeds the supported date
      *             range
      * @throws ZoneRulesException if the converted zone region ID cannot be found
@@ -161,9 +160,7 @@ public class DateTimeType implements PrimitiveType, State, Command {
      * Create a {@link DateTimeType} being the translation of the current object to a given zone
      *
      * @param zone the target zone as a string
-     *
      * @return a {@link DateTimeType} translated to the given zone
-     *
      * @throws DateTimeException if the zone has an invalid format or the result exceeds the supported date range
      * @throws ZoneRulesException if the zone is a region ID that cannot be found
      */
@@ -175,9 +172,7 @@ public class DateTimeType implements PrimitiveType, State, Command {
      * Create a {@link DateTimeType} being the translation of the current object to a given zone
      *
      * @param zoneId the target {@link ZoneId}
-     *
      * @return a {@link DateTimeType} translated to the given zone
-     *
      * @throws DateTimeException if the result exceeds the supported date range
      */
     public DateTimeType toZone(ZoneId zoneId) throws DateTimeException {

bundles/org.openhab.core/src/main/java/org/eclipse/smarthome/core/library/types/HSBType.java

@@ -164,7 +164,6 @@ public class HSBType extends PercentType implements ComplexType, State, Command
      * Returned color is set to full brightness
      *
      * @param x, y color information 0.0 - 1.0
-     *
      * @return new HSBType object representing the given CIE XY color, full brightness
      */
     public static HSBType fromXY(float x, float y) {

bundles/org.openhab.core/src/main/java/org/eclipse/smarthome/core/types/StateDescriptionFragmentProvider.java

@@ -32,7 +32,6 @@ public interface StateDescriptionFragmentProvider {
      *
      * @param itemName item name (must not be null)
      * @param locale locale (can be null)
-     *
      * @return a {@link StateDescriptionFragment} with only the parts known by this
      *         {@link StateDescriptionFragmentProvider}.
      */