Index: trunk/src/org/openstreetmap/josm/actions/ActionParameter.java
===================================================================
--- trunk/src/org/openstreetmap/josm/actions/ActionParameter.java	(revision 12544)
+++ trunk/src/org/openstreetmap/josm/actions/ActionParameter.java	(revision 12546)
@@ -4,22 +4,55 @@
 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> {
 
Index: trunk/src/org/openstreetmap/josm/actions/AdaptableAction.java
===================================================================
--- trunk/src/org/openstreetmap/josm/actions/AdaptableAction.java	(revision 12544)
+++ trunk/src/org/openstreetmap/josm/actions/AdaptableAction.java	(revision 12546)
@@ -4,5 +4,15 @@
 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 {
 }
Index: trunk/src/org/openstreetmap/josm/actions/ParameterizedAction.java
===================================================================
--- trunk/src/org/openstreetmap/josm/actions/ParameterizedAction.java	(revision 12544)
+++ trunk/src/org/openstreetmap/josm/actions/ParameterizedAction.java	(revision 12546)
@@ -6,8 +6,21 @@
 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);
 }
Index: trunk/src/org/openstreetmap/josm/actions/ParameterizedActionDecorator.java
===================================================================
--- trunk/src/org/openstreetmap/josm/actions/ParameterizedActionDecorator.java	(revision 12544)
+++ trunk/src/org/openstreetmap/josm/actions/ParameterizedActionDecorator.java	(revision 12546)
@@ -9,4 +9,8 @@
 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,4 +18,9 @@
     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,4 +63,8 @@
     }
 
+    /**
+     * 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;