Javadoc is fixed #3269 (#3279)

* Javadoc is updated

Signed-off-by: Plamen Veselinov Peev <p.peev@prosyst.bg>

bundles/automation/org.eclipse.smarthome.automation.api/src/main/java/org/eclipse/smarthome/automation/Action.java

@@ -9,7 +9,6 @@
 
 import java.util.Collections;
 import java.util.Map;
-import java.util.Set;
 
 import org.eclipse.smarthome.automation.type.ActionType;
 import org.eclipse.smarthome.automation.type.Input;
@@ -22,8 +21,7 @@
  * Elements of this section are expected result of {@link Rule} execution. The
  * Action can have {@link Output} elements. These actions are used to process
  * input data as source data of other Actions. Building elements of actions ( {@link ConfigDescriptionParameter}s,
- * {@link Input}s and {@link Output}s) are
- * defined by {@link ActionType}
+ * {@link Input}s and {@link Output}s) are defined by {@link ActionType}
  *
  * @author Yordan Mihaylov - Initial Contribution
  * @author Ana Dimova - Initial Contribution
@@ -51,10 +49,10 @@ public Action(String UID, String typeUID, Configuration configuration, Map<Strin
 
     /**
      * This method is used to get input connections of the Action. The connections
-     * are links between {@link Input}s of the {@link Module} and {@link Output}s
+     * are links between {@link Input}s of the this {@link Module} and {@link Output}s
      * of other {@link Module}s.
      *
-     * @return a {@link Set} of input {@link Input}s.
+     * @return map that contains the inputs of this action.
      */
     public Map<String, String> getInputs() {
         return inputs != null ? inputs : Collections.<String, String> emptyMap();
@@ -63,7 +61,7 @@ public Map<String, String> getInputs() {
     /**
      * This method is used to connect {@link Input}s of the action to {@link Output}s of other {@link Module}s.
      *
-     * @param connections a {@link Set} of input {@link Input}s.
+     * @param inputs map that contains the inputs for this action.
      */
     public void setInputs(Map<String, String> inputs) {
         if (inputs != null) {

bundles/automation/org.eclipse.smarthome.automation.api/src/main/java/org/eclipse/smarthome/automation/Condition.java

@@ -9,7 +9,6 @@
 
 import java.util.Collections;
 import java.util.Map;
-import java.util.Set;
 
 import org.eclipse.smarthome.automation.type.ConditionType;
 import org.eclipse.smarthome.automation.type.Input;
@@ -47,11 +46,11 @@ public Condition(String id, String typeUID, Configuration configuration, Map<Str
     }
 
     /**
-     * This method is used to get input connections of the Condition. The
-     * connections are links between {@link Input}s of the current {@link Module} and {@link Output}s of other
+     * This method is used to get input connections of the Condition. The connections
+     * are links between {@link Input}s of the current {@link Module} and {@link Output}s of other
      * {@link Module}s.
      *
-     * @return a {@link Map} of input connections.
+     * @return map that contains the inputs of this condition.
      */
     public Map<String, String> getInputs() {
         return inputs != null ? inputs : Collections.<String, String> emptyMap();
@@ -60,7 +59,7 @@ public Map<String, String> getInputs() {
     /**
      * This method is used to connect {@link Input}s of the Condition to {@link Output}s of other {@link Module}s.
      *
-     * @param connections a {@link Set} of input {@link Input}s.
+     * @param inputs map that contains the inputs for this condition.
      */
     public void setInputs(Map<String, String> inputs) {
         if (inputs != null) {

bundles/automation/org.eclipse.smarthome.automation.api/src/main/java/org/eclipse/smarthome/automation/Rule.java

@@ -136,24 +136,27 @@ public void setName(String ruleName) throws IllegalStateException {
 
     /**
      * Rules can have
+     * <ul>
      * <li><code>tags</code> - non-hierarchical keywords or terms for describing them. This method is
-     * used for getting the tags assign to this Rule. The tags are used to filter the rules.
+     * used for getting the tags assign to this Rule. The tags are used to filter the rules.</li>
+     * </ul>
      *
-     * @return a list of tags
+     * @return a {@link Set} of tags
      */
     public Set<String> getTags() {
         return tags = tags != null ? tags : Collections.<String> emptySet();
     }
 
     /**
      * Rules can have
+     * <ul>
      * <li><code>tags</code> - non-hierarchical keywords or terms for describing them. This method is
      * used for setting the tags to this rule. This property can be changed only when the Rule is not in active state.
-     * The tags are used to filter the rules.
+     * The tags are used to filter the rules.</li>
+     * </ul>
      *
      * @param ruleTags list of tags assign to this Rule.
-     * @throws IllegalStateException IllegalStateException when the rule is in
-     *             active state.
+     * @throws IllegalStateException when the rule is in active state.
      */
     public void setTags(Set<String> ruleTags) throws IllegalStateException {
         tags = ruleTags != null ? ruleTags : Collections.<String> emptySet();
@@ -223,9 +226,8 @@ public void setConfiguration(Configuration ruleConfiguration) {
     }
 
     /**
-     * This method is used for getting the Set with {@link ConfigDescriptionParameter}s defining meta info for
-     * configuration
-     * properties of the Rule.<br/>
+     * This method is used for getting the {@link List} with {@link ConfigDescriptionParameter}s
+     * defining meta info for configuration properties of the Rule.
      *
      * @return a {@link Set} of {@link ConfigDescriptionParameter}s.
      */
@@ -310,7 +312,7 @@ private <T extends Module> T getModule(String moduleUID, List<T> modules) {
     }
 
     /**
-     * This method is used to return a group of module of this rule
+     * This method is used to return the module of this rule.
      *
      * @param moduleClazz optional parameter defining type looking modules. The
      *            types are {@link Trigger}, {@link Condition} or {@link Action}

bundles/automation/org.eclipse.smarthome.automation.api/src/main/java/org/eclipse/smarthome/automation/RuleRegistry.java

@@ -16,10 +16,10 @@
  * The {@link RuleRegistry} provides basic functionality for managing {@link Rule}s.
  * It can be used to
  * <ul>
- * <li>Add Rules with the {@link #add(Rule)} method.</li>
+ * <li>Add Rules with the {@link Registry#add(Object)} method.</li>
  * <li>Get the existing rules with the {@link #getByTag(String)}, {@link #getByTags(String[])} methods.</li>
- * <li>Update the existing rules with the {@link #update(Rule)} method.</li>
- * <li>Remove Rules with the {@link #remove(String)} method.</li>
+ * <li>Update the existing rules with the {@link Registry#update(Object)} method.</li>
+ * <li>Remove Rules with the {@link Registry#remove(Object)} method.</li>
  * <li>Manage the state (<b>enabled</b> or <b>disabled</b>) of the Rules:
  * <ul>
  * <li>A newly added Rule is always <b>enabled</b>.</li>
@@ -107,23 +107,23 @@ public interface RuleRegistry extends Registry<Rule, String> {
     public Boolean isEnabled(String ruleUID);
 
     /**
-     * The method "runNow(ruleUID)" skips triggers&conditions and directly executes the actions of the rule.
+     * The method "runNow(ruleUID)" skips the triggers and the conditions and directly executes the actions of the rule.
      * This should always be possible unless an action has a mandatory input that is linked to a trigger.
      * In that case the action is skipped and the RuleEngine continues execution of rest actions.
      *
-     * @param ruleUID id of rule whose actions have to be executed.
+     * @param ruleUID id of rule whose actions have to be executed
      *
      */
     public void runNow(String ruleUID);
-    
+
     /**
-	 * Same as {@link RuleRegistry#runNow(String)} with additional option to enable/disable evaluation of
-	 * conditions defined in the target rule. The context can be set here, too but also might be null.
-	 * 
-	 * @param ruleUID
-	 * @param considerConditions
-	 * @param context
-	 */
-	public void runNow(String ruleUID, boolean considerConditions, Map<String, Object> context);
+     * Same as {@link RuleRegistry#runNow(String)} with additional option to enable/disable evaluation of
+     * conditions defined in the target rule. The context can be set here, too but also might be null.
+     *
+     * @param ruleUID id of rule whose actions have to be executed
+     * @param considerConditions if <code>true</code> the conditions will be checked
+     * @param context the context that is passed to the conditions and the actions
+     */
+    public void runNow(String ruleUID, boolean considerConditions, Map<String, Object> context);
 
 }

bundles/automation/org.eclipse.smarthome.automation.api/src/main/java/org/eclipse/smarthome/automation/events/AbstractRuleRegistryEvent.java

@@ -24,20 +24,18 @@ public abstract class AbstractRuleRegistryEvent extends AbstractEvent {
     /**
      * Must be called in subclass constructor to create a new rule registry event.
      *
-     * @param topic
-     * @param payload
-     * @param source
-     * @param ruleDTO
+     * @param topic the topic of the event
+     * @param payload the payload of the event
+     * @param source the source of the event
+     * @param ruleDTO the ruleDTO for which this event is created
      */
     public AbstractRuleRegistryEvent(String topic, String payload, String source, RuleDTO rule) {
         super(topic, payload, source);
         this.rule = rule;
     }
 
     /**
-     * returns the RuleDTO which caused the Event
-     *
-     * @return
+     * @return the RuleDTO which caused the Event
      */
     public RuleDTO getRule() {
         return this.rule;

bundles/automation/org.eclipse.smarthome.automation.api/src/main/java/org/eclipse/smarthome/automation/events/RuleAddedEvent.java

@@ -23,10 +23,10 @@ public class RuleAddedEvent extends AbstractRuleRegistryEvent {
     /**
      * constructs a new rule added event
      *
-     * @param topic
-     * @param payload
-     * @param source
-     * @param ruleDTO
+     * @param topic the topic of the event
+     * @param payload the payload of the event
+     * @param source the source of the event
+     * @param ruleDTO the rule for which this event is created
      */
     public RuleAddedEvent(String topic, String payload, String source, RuleDTO rule) {
         super(topic, payload, source, rule);

bundles/automation/org.eclipse.smarthome.automation.api/src/main/java/org/eclipse/smarthome/automation/events/RuleEventFactory.java

@@ -102,12 +102,12 @@ private String getRuleId(String topic) {
     }
 
     /**
-     * creates a rule updated event
+     * Creates a rule updated event
      *
-     * @param rule the updated rule
-     * @param oldRule the old rule
-     * @param source
-     * @return
+     * @param rule the new rule
+     * @param oldRule the rule that has been updated
+     * @param source the source of the event
+     * @return {@link RuleUpdatedEvent} instance
      */
     public static RuleUpdatedEvent createRuleUpdatedEvent(Rule rule, Rule oldRule, String source) {
         String topic = buildTopic(RULE_UPDATED_EVENT_TOPIC, rule);
@@ -121,12 +121,12 @@ public static RuleUpdatedEvent createRuleUpdatedEvent(Rule rule, Rule oldRule, S
     }
 
     /**
-     * creates a rule status info event
+     * Creates a rule status info event
      *
-     * @param statusInfo
-     * @param rule
-     * @param source
-     * @return
+     * @param statusInfo the status info of the event
+     * @param ruleUID the UID of the rule for which the event is created
+     * @param source the source of the event
+     * @return {@link RuleStatusInfoEvent} instance
      */
     public static RuleStatusInfoEvent createRuleStatusInfoEvent(RuleStatusInfo statusInfo, String ruleUID,
             String source) {
@@ -136,11 +136,11 @@ public static RuleStatusInfoEvent createRuleStatusInfoEvent(RuleStatusInfo statu
     }
 
     /**
-     * creates a rule removed event
+     * Creates a rule removed event
      *
-     * @param rule
-     * @param source
-     * @return
+     * @param rule the rule for which this event is created
+     * @param source the source of the event
+     * @return {@link RuleRemovedEvent} instance
      */
     public static RuleRemovedEvent createRuleRemovedEvent(Rule rule, String source) {
         String topic = buildTopic(RULE_REMOVED_EVENT_TOPIC, rule);
@@ -150,11 +150,11 @@ public static RuleRemovedEvent createRuleRemovedEvent(Rule rule, String source)
     }
 
     /**
-     * creates a rule added event
+     * Creates a rule added event
      *
-     * @param rule
-     * @param source
-     * @return
+     * @param rule the rule for which this event is created
+     * @param source the source of the event
+     * @return {@link RuleAddedEvent} instance
      */
     public static RuleAddedEvent createRuleAddedEvent(Rule rule, String source) {
         String topic = buildTopic(RULE_ADDED_EVENT_TOPIC, rule);

bundles/automation/org.eclipse.smarthome.automation.api/src/main/java/org/eclipse/smarthome/automation/events/RuleRemovedEvent.java

@@ -21,12 +21,12 @@ public class RuleRemovedEvent extends AbstractRuleRegistryEvent {
     public static final String TYPE = RuleRemovedEvent.class.getSimpleName();
 
     /**
-     * constructs a new rule removed event
+     * Constructs a new rule removed event
      *
-     * @param topic
-     * @param payload
-     * @param source
-     * @param ruleDTO
+     * @param topic the topic of the event
+     * @param payload the payload of the event
+     * @param source the source of the event
+     * @param rule the rule for which this event is
      */
     public RuleRemovedEvent(String topic, String payload, String source, RuleDTO rule) {
         super(topic, payload, source, rule);

bundles/automation/org.eclipse.smarthome.automation.api/src/main/java/org/eclipse/smarthome/automation/events/RuleStatusInfoEvent.java

@@ -28,10 +28,11 @@ public class RuleStatusInfoEvent extends AbstractEvent {
     /**
      * constructs a new rule status event
      *
-     * @param topic
-     * @param payload
-     * @param source
-     * @param ruleDTO
+     * @param topic the topic of the event
+     * @param payload the payload of the event
+     * @param source the source of the event
+     * @param statusInfo the status info for this event
+     * @param ruleId the rule for which this event is
      */
     public RuleStatusInfoEvent(String topic, String payload, String source, RuleStatusInfo statusInfo, String ruleId) {
         super(topic, payload, source);

bundles/automation/org.eclipse.smarthome.automation.api/src/main/java/org/eclipse/smarthome/automation/events/RuleUpdatedEvent.java

@@ -25,10 +25,11 @@ public class RuleUpdatedEvent extends AbstractRuleRegistryEvent {
     /**
      * constructs a new rule updated event
      *
-     * @param topic
-     * @param payload
-     * @param source
-     * @param ruleDTO
+     * @param topic the topic of the event
+     * @param payload the payload of the event
+     * @param source the source of the event
+     * @param rule the rule for which is this event
+     * @param oldRule the rule that has been updated
      */
     public RuleUpdatedEvent(String topic, String payload, String source, RuleDTO rule, RuleDTO oldRule) {
         super(topic, payload, source, rule);

bundles/automation/org.eclipse.smarthome.automation.api/src/main/java/org/eclipse/smarthome/automation/handler/ModuleHandlerFactory.java

@@ -27,25 +27,24 @@ public interface ModuleHandlerFactory {
     /**
      * This method is used to return UIDs of module types supported by this {@link ModuleHandlerFactory}
      *
-     * @return collection of module type unequal ids supported by this factory.
+     * @return collection of module type unequal UID supported by this factory.
      */
     public Collection<String> getTypes();
 
     /**
      * This method is used to get a ModuleHandler instance for the passed module
      * instance
      *
-     * @param module module instance for which the {@link ModuleHandler} instance is
-     *            created for.
-     *
-     * @return ModuleHandler instance.
+     * @param module module instance for which the {@link ModuleHandler} instance is created.
+     * @param ruleUID the UID of the rule for which the handler instance is created.
+     * @return {@link ModuleHandler} instance.
      */
     public ModuleHandler getHandler(Module module, String ruleUID);
 
     /**
-     * This method signalizes the Factory that a ModuleHandler for the passed module is not needed anymore. Implementors
+     * This method signalises the Factory that a ModuleHandler for the passed module is not needed anymore. Implementors
      * must take care of invalidating caches and disposing the Handlers.
-     * 
+     *
      * @param module
      */
     public void ungetHandler(Module module, String ruleUID, ModuleHandler handler);