Changeset 12546 in josm for trunk

Timestamp:

2017-07-31T11:38:47+02:00 (7 years ago)

Author:

bastiK

Message:

see #14794 - javadoc

Location:

trunk/src/org/openstreetmap/josm/actions

Files:

• ActionParameter.java (modified) (1 diff)
• AdaptableAction.java (modified) (1 diff)
• ParameterizedAction.java (modified) (1 diff)
• ParameterizedActionDecorator.java (modified) (3 diffs)

trunk/src/org/openstreetmap/josm/actions/ActionParameter.java

@@ -4 +4 @@
 import org.openstreetmap.josm.actions.search.SearchAction.SearchSetting;
 
+/**
+ * Abstract class for <i>key=value</i> parameters, used in {@link ParameterizedAction}.
+ * <p>
+ * The key ({@link #name}) is a string and the value of class {@link T}. The value can be
+ * converted to and from a string.
+ * @param <T> the value type
+ */
 public abstract class ActionParameter<T> {
 
     private final String name;
 
+    /**
+     * Constructs a new ActionParameter.
+     * @param name parameter name (the key)
+     */
     public ActionParameter(String name) {
         this.name = name;
     }
 
+    /**
+     * Get the name of this action parameter.
+     * The name is used as a key, to look up values for the parameter.
+     * @return the name of this action parameter
+     */
     public String getName() {
         return name;
     }
 
+    /**
+     * Get the value type of this action parameter.
+     * @return the value type of this action parameter
+     */
     public abstract Class<T> getType();
 
+    /**
+     * Convert a given value into a string (serialization).
+     * @param value the value
+     * @return a string representation of the value
+     */
     public abstract String writeToString(T value);
 
+    /**
+     * Create a value from the given string representation (deserialization).
+     * @param s the string representation of the value
+     * @return the corresponding value object
+     */
     public abstract T readFromString(String s);
 
+    /**
+     * Simple ActionParameter implementation for string values.
+     */
     public static class StringActionParameter extends ActionParameter<String> {
 

trunk/src/org/openstreetmap/josm/actions/AdaptableAction.java

@@ -4 +4 @@
 import javax.swing.Action;
 
-/* allow us to tell the toolbar that name and icon may be changed */
+/**
+ * Interface to indicate that name (tooltip) and icon may be changed for an entry
+ * in the toolbar.
+ * <p>
+ * The name and icon of an {@link org.openstreetmap.josm.gui.preferences.ToolbarPreferences.ActionDefinition}
+ * is saved to the preferences when the wrapped action implements AdaptableAction.
+ * <p>
+ * The user will have options to change the name and icon in the
+ * {@link org.openstreetmap.josm.gui.preferences.ToolbarPreferences} when the action
+ * for the toolbar entry implements AdaptableAction.
+ */
 public interface AdaptableAction extends Action {
 }

trunk/src/org/openstreetmap/josm/actions/ParameterizedAction.java

@@ -6 +6 @@
 import java.util.Map;
 
+/**
+ * Interface for (toolbar-)actions that have additional parameters which need
+ * to be saved to the preferences (and loaded back).
+ */
 public interface ParameterizedAction extends AdaptableAction {
 
+    /**
+     * Get the list of parameters that describe the action.
+     * @return the list of parameters that describe the action
+     */
     List<ActionParameter<?>> getActionParameters();
 
+    /**
+     * Invoke action using the given parameters.
+     * @param e the ActionEvent
+     * @param parameters parameter map
+     */
     void actionPerformed(ActionEvent e, Map<String, Object> parameters);
 }

trunk/src/org/openstreetmap/josm/actions/ParameterizedActionDecorator.java

@@ -9 +9 @@
 import javax.swing.Action;
 
+/**
+ * Action wrapper that delegates to a {@link ParameterizedAction} object using
+ * a specific set of parameters.
+ */
 public class ParameterizedActionDecorator implements Action {
 
@@ -14 +18 @@
     private final Map<String, Object> parameters;
 
+    /**
+     * Constructs a new ParameterizedActionDecorator.
+     * @param action the action that is invoked by this wrapper
+     * @param parameters parameters used for invoking the action
+     */
     public ParameterizedActionDecorator(ParameterizedAction action, Map<String, Object> parameters) {
         this.action = action;
@@ -54 +63 @@
     }
 
+    /**
+     * Get the parameters used to invoke the wrapped action.
+     * @return the parameters used to invoke the wrapped action
+     */
     public Map<String, Object> getParameters() {
         return parameters;