javadocs; deprecate RunnableState interface and remove it from inheritance hierarchy

java/execution/openapi/src/com/intellij/execution/configurations/PatchedRunnableState.java

@@ -15,6 +15,6 @@
  */
 package com.intellij.execution.configurations;
 
-public interface PatchedRunnableState extends RunnableState{
+public interface PatchedRunnableState extends RunProfileState {
   RunnerSettings getPatcher();
 }

platform/external-system-impl/src/com/intellij/openapi/externalSystem/service/execution/ExternalSystemRunConfiguration.java

@@ -131,7 +131,7 @@ public class ExternalSystemRunConfiguration extends RunConfigurationBase impleme
   public void checkConfiguration() throws RuntimeConfigurationException {
   }
   
-  public static class MyRunnableState implements RunnableState {
+  public static class MyRunnableState implements RunProfileState {
     
     @NotNull private final ExternalSystemTaskExecutionSettings mySettings;
     @NotNull private final Project myProject;

platform/lang-api/src/com/intellij/execution/configurations/CommandLineState.java

@@ -33,7 +33,7 @@ import com.intellij.openapi.project.DumbAware;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
-public abstract class CommandLineState implements RunnableState {
+public abstract class CommandLineState implements RunProfileState {
   private static final Logger LOG = Logger.getInstance("#com.intellij.execution.configurations.CommandLineState");
   private TextConsoleBuilder myConsoleBuilder;
 

platform/lang-api/src/com/intellij/execution/configurations/ConfigurationFactory.java

@@ -25,6 +25,9 @@ import org.jetbrains.annotations.NotNull;
 import javax.swing.*;
 
 /**
+ * Factory for run configuration instances.
+ *
+ * @see com.intellij.execution.configurations.ConfigurationType#getConfigurationFactories()
  * @author dyoma
  */
 public abstract class ConfigurationFactory {
@@ -36,18 +39,36 @@ public abstract class ConfigurationFactory {
     myType = type;
   }
 
+  /**
+   * Creates a new run configuration with the specified name by cloning the specified template.
+   *
+   * @param name the name for the new run configuration.
+   * @param template the template from which the run configuration is copied
+   * @return the new run configuration.
+   */
   public RunConfiguration createConfiguration(String name, RunConfiguration template) {
     RunConfiguration newConfiguration = template.clone();
     newConfiguration.setName(name);
     return newConfiguration;
   }
 
+  /**
+   * Creates a new template run configuration within the context of the specified project.
+   *
+   * @param project the project in which the run configuration will be used
+   * @return the run configuration instance.
+   */
   public abstract RunConfiguration createTemplateConfiguration(Project project);
 
   public RunConfiguration createTemplateConfiguration(Project project, RunManager runManager) {
     return createTemplateConfiguration(project);
   }
 
+  /**
+   * Returns the name of the run configuration variant created by this factory.
+   *
+   * @return the name of the run configuration variant created by this factory
+   */
   public String getName() {
     return myType.getDisplayName();
   }

platform/lang-api/src/com/intellij/execution/configurations/ConfigurationType.java

@@ -21,15 +21,51 @@ import org.jetbrains.annotations.NotNull;
 
 import javax.swing.*;
 
+/**
+ * The type of a run configuration.
+ *
+ * @see ConfigurationTypeBase
+ */
 public interface ConfigurationType {
   ExtensionPointName<ConfigurationType> CONFIGURATION_TYPE_EP = ExtensionPointName.create("com.intellij.configurationType");
 
+  /**
+   * Returns the display name of the configuration type. This is used, for example, to represent the configuration type in the run
+   * configurations tree, and also as the name of the action used to create the configuration.
+   *
+   * @return the display name of the configuration type.
+   */
   String getDisplayName();
+
+  /**
+   * Returns the description of the configuration type. You may return the same text as the display name of the configuration type.
+   *
+   * @return the description of the configuration type.
+   */
   String getConfigurationTypeDescription();
+
+  /**
+   * Returns the 16x16 icon used to represent the configuration type.
+   *
+   * @return the icon
+   */
   Icon getIcon();
 
+  /**
+   * Returns the ID of the configuration type. The ID is used to store run configuration settings in a project or workspace file and
+   * must not change between plugin versions.
+   *
+   * @return the configuration type ID.
+   */
   @NonNls @NotNull
   String getId();
 
+  /**
+   * Returns the configuration factories used by this configuration type. Normally each configuration type provides just a single factory.
+   * You can return multiple factories if your configurations can be created in multiple variants (for example, local and remote for an
+   * application server).
+   *
+   * @return the run configuration factories.
+   */
   ConfigurationFactory[] getConfigurationFactories();
 }

platform/lang-api/src/com/intellij/execution/configurations/RunProfile.java

@@ -23,17 +23,45 @@ import org.jetbrains.annotations.Nullable;
 
 import javax.swing.*;
 
+/**
+ * Base interface for run configurations.
+ *
+ * @see RunConfiguration
+ * @see ConfigurationFactory#createTemplateConfiguration(com.intellij.openapi.project.Project)
+ */
 public interface RunProfile {
    /**
-    * todo - javadoc
+    * Prepares for executing a specific instance of the run configuration.
+    *
+    * @param executor the execution mode selected by the user (run, debug, profile etc.)
+    * @param env the environment object containing additional settings for executing the configuration.
+    * @return the RunProfileState describing the process which is about to be started, or null if it's impossible to start the process.
     */
   @Nullable
-  RunProfileState getState(@NotNull Executor executor, @NotNull ExecutionEnvironment env) throws ExecutionException ;
+  RunProfileState getState(@NotNull Executor executor, @NotNull ExecutionEnvironment env) throws ExecutionException;
 
+  /**
+   * Returns the name of the run configuration.
+   *
+   * @return the name of the run configuration.
+   */
   String getName();
 
+  /**
+   * Returns the icon for the run configuration.
+   *
+   * @return the icon for the run configuration.
+   */
   @Nullable
   Icon getIcon();
 
+  /**
+   * Checks whether the run configuration settings are valid.
+   *
+   * @throws RuntimeConfigurationException if the configuration settings contain a non-fatal problem which the user should be warned about
+   * but the execution should still be allowed
+   * @throws RuntimeConfigurationError if the configuration settings contain a fatal problem which makes it impossible to execute the run
+   * configuration.
+   */
   void checkConfiguration() throws RuntimeConfigurationException;
 }

platform/lang-api/src/com/intellij/execution/configurations/RunnableState.java

@@ -15,5 +15,8 @@
  */
 package com.intellij.execution.configurations;
 
+/**
+ * @deprecated this interface doesn't have any purpose, please don't use it
+ */
 public interface RunnableState extends RunProfileState {
 }