diff --git a/platform/lang-api/src/com/intellij/execution/runners/ProgramRunner.java b/platform/lang-api/src/com/intellij/execution/runners/ProgramRunner.java
index 0cdb40f195f0..3609893ab854 100644
--- a/platform/lang-api/src/com/intellij/execution/runners/ProgramRunner.java
+++ b/platform/lang-api/src/com/intellij/execution/runners/ProgramRunner.java
@@ -28,6 +28,10 @@ import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
 /**
+ * A ProgramRunner is responsible for the execution workflow of certain types of run configurations with a certain executor. For example,
+ * one ProgramRunner can be responsible for debugging all Java-based run configurations (applications, JUnit tests, etc.); the run
+ * configuration takes care of building a command line and the program runner takes care of how exactly it needs to be executed.
+ *
  * A newly created program runner should be registered in a corresponding plugin.xml:
  *
  * <extensions defaultExtensionNs="com.intellij">
@@ -35,6 +39,7 @@ import org.jetbrains.annotations.Nullable;
  * </extensions>
  *
  * @param <Settings>
+ * @see GenericProgramRunner
  */
 public interface ProgramRunner<Settings extends RunnerSettings> {
   ExtensionPointName<ProgramRunner> PROGRAM_RUNNER_EP = ExtensionPointName.create("com.intellij.programRunner");
@@ -43,11 +48,29 @@ public interface ProgramRunner<Settings extends RunnerSettings> {
     void processStarted(RunContentDescriptor descriptor);
   }
 
+  /**
+   * Returns the unique ID of this runner. This ID is used to store settings and must not change between plugin versions.
+   *
+   * @return the program runner ID.
+   */
   @NotNull @NonNls
   String getRunnerId();
 
+  /**
+   * Checks if the program runner is capable of running the specified configuration with the specified executor.
+   *
+   * @param executorId ID of the {@link Executor} with which the user is trying to run the configuration.
+   * @param profile the configuration being run.
+   * @return true if the runner can handle it, false otherwise.
+   */
   boolean canRun(@NotNull final String executorId, @NotNull final RunProfile profile);
 
+  /**
+   * Creates a block of per-configuration settings used by this program runner.
+   *
+   * @param settingsProvider source of assorted information about the configuration being edited.
+   * @return the per-runner settings, or null if this runner doesn't use any per-runner settings.
+   */
   @Nullable
   Settings createConfigurationData(ConfigurationInfoProvider settingsProvider);