diff --git a/platform/lang-impl/src/com/intellij/application/options/editor/AutoImportOptionsProvider.java b/platform/lang-impl/src/com/intellij/application/options/editor/AutoImportOptionsProvider.java
index 989d2e344a4b..7ea36976b846 100644
--- a/platform/lang-impl/src/com/intellij/application/options/editor/AutoImportOptionsProvider.java
+++ b/platform/lang-impl/src/com/intellij/application/options/editor/AutoImportOptionsProvider.java
@@ -17,9 +17,16 @@
 package com.intellij.application.options.editor;
 
 import com.intellij.openapi.options.UnnamedConfigurable;
-import com.intellij.openapi.extensions.ExtensionPointName;
 
 /**
+ * Register implementation of this interface in the plugin.xml:
+ * <p/>
+ * &lt;extensions defaultExtensionNs="com.intellij"&gt;<br>
+ * &nbsp;&nbsp;&lt;autoImportOptionsProvider instance="class-name"/&gt;<br>
+ * &lt;/extensions&gt;
+ * <p>
+ * A new instance of the specified class will be created each time then the Settings dialog is opened
+ *
  * @author Dmitry Avdeev
  */
 public interface AutoImportOptionsProvider extends UnnamedConfigurable {
diff --git a/platform/lang-impl/src/com/intellij/application/options/editor/CodeFoldingOptionsProvider.java b/platform/lang-impl/src/com/intellij/application/options/editor/CodeFoldingOptionsProvider.java
index 9de4c8981688..262c50ec45ba 100644
--- a/platform/lang-impl/src/com/intellij/application/options/editor/CodeFoldingOptionsProvider.java
+++ b/platform/lang-impl/src/com/intellij/application/options/editor/CodeFoldingOptionsProvider.java
@@ -20,8 +20,16 @@
  */
 package com.intellij.application.options.editor;
 
-import com.intellij.openapi.extensions.ExtensionPointName;
 import com.intellij.openapi.options.UnnamedConfigurable;
 
+/**
+ * Register implementation of this interface in the plugin.xml:
+ * <p/>
+ * &lt;extensions defaultExtensionNs="com.intellij"&gt;<br>
+ * &nbsp;&nbsp;&lt;codeFoldingOptionsProvider instance="class-name"/&gt;<br>
+ * &lt;/extensions&gt;
+ * <p>
+ * A new instance of the specified class will be created each time then the Settings dialog is opened
+ */
 public interface CodeFoldingOptionsProvider extends UnnamedConfigurable {
 }
\ No newline at end of file
diff --git a/platform/lang-impl/src/com/intellij/application/options/editor/EditorAppearanceConfigurable.java b/platform/lang-impl/src/com/intellij/application/options/editor/EditorAppearanceConfigurable.java
index 17a75f6cfc04..409f23d540cb 100644
--- a/platform/lang-impl/src/com/intellij/application/options/editor/EditorAppearanceConfigurable.java
+++ b/platform/lang-impl/src/com/intellij/application/options/editor/EditorAppearanceConfigurable.java
@@ -37,6 +37,14 @@ import java.awt.event.ActionListener;
 import java.util.List;
 
 /**
+ * To provide an additional settings editor register implementation of {@link com.intellij.openapi.options.UnnamedConfigurable} in the plugin.xml:
+ * <p/>
+ * &lt;extensions defaultExtensionNs="com.intellij"&gt;<br>
+ * &nbsp;&nbsp;&lt;editorAppearanceConfigurable instance="class-name"/&gt;<br>
+ * &lt;/extensions&gt;
+ * <p>
+ * A new instance of the specified class will be created each time then the Settings dialog is opened
+ *
  * @author yole
  */
 public class EditorAppearanceConfigurable extends CompositeConfigurable<UnnamedConfigurable> implements EditorOptionsProvider {
diff --git a/platform/lang-impl/src/com/intellij/application/options/editor/EditorOptionsProvider.java b/platform/lang-impl/src/com/intellij/application/options/editor/EditorOptionsProvider.java
index d538200a01b3..79a50589ac50 100644
--- a/platform/lang-impl/src/com/intellij/application/options/editor/EditorOptionsProvider.java
+++ b/platform/lang-impl/src/com/intellij/application/options/editor/EditorOptionsProvider.java
@@ -22,5 +22,14 @@ package com.intellij.application.options.editor;
 
 import com.intellij.openapi.options.SearchableConfigurable;
 
+/**
+ * Register implementation of this interface in the plugin.xml:
+ * <p/>
+ * &lt;extensions defaultExtensionNs="com.intellij"&gt;<br>
+ * &nbsp;&nbsp;&lt;editorOptionsProvider instance="class-name"/&gt;<br>
+ * &lt;/extensions&gt;
+ * <p>
+ * A new instance of the specified class will be created each time then the Settings dialog is opened
+ */
 public interface EditorOptionsProvider extends SearchableConfigurable {
 }
\ No newline at end of file
diff --git a/platform/lang-impl/src/com/intellij/application/options/editor/EditorSmartKeysConfigurable.java b/platform/lang-impl/src/com/intellij/application/options/editor/EditorSmartKeysConfigurable.java
index 494087cb246d..1212010995a1 100644
--- a/platform/lang-impl/src/com/intellij/application/options/editor/EditorSmartKeysConfigurable.java
+++ b/platform/lang-impl/src/com/intellij/application/options/editor/EditorSmartKeysConfigurable.java
@@ -37,6 +37,14 @@ import java.util.Collection;
 import java.util.List;
 
 /**
+ * To provide an additional settings editor register implementation of {@link com.intellij.openapi.options.UnnamedConfigurable} in the plugin.xml:
+ * <p/>
+ * &lt;extensions defaultExtensionNs="com.intellij"&gt;<br>
+ * &nbsp;&nbsp;&lt;editorSmartKeysConfigurable instance="class-name"/&gt;<br>
+ * &lt;/extensions&gt;
+ * <p>
+ * A new instance of the specified class will be created each time then the Settings dialog is opened
+ *
  * @author yole
  */
 public class EditorSmartKeysConfigurable extends CompositeConfigurable<UnnamedConfigurable> implements EditorOptionsProvider {
diff --git a/platform/lang-impl/src/com/intellij/openapi/options/ModuleConfigurableEP.java b/platform/lang-impl/src/com/intellij/openapi/options/ModuleConfigurableEP.java
index 92973e11f8e6..19461b1c0205 100644
--- a/platform/lang-impl/src/com/intellij/openapi/options/ModuleConfigurableEP.java
+++ b/platform/lang-impl/src/com/intellij/openapi/options/ModuleConfigurableEP.java
@@ -18,6 +18,14 @@ package com.intellij.openapi.options;
 import com.intellij.openapi.module.Module;
 
 /**
+ * To provide an additional tab for a module editor register implementation of {@link Configurable} in the plugin.xml:
+ * <p/>
+ * &lt;extensions defaultExtensionNs="com.intellij"&gt;<br>
+ * &nbsp;&nbsp;&lt;moduleConfigurable instance="class-name"/&gt;<br>
+ * &lt;/extensions&gt;
+ * <p>
+ * A new instance of the specified class will be created each time then the Project Structure dialog is opened
+ *
  * @author nik
  */
 public class ModuleConfigurableEP extends AbstractConfigurableEP<Configurable> {
diff --git a/platform/lang-impl/src/com/intellij/profile/codeInspection/ui/ErrorOptionsProvider.java b/platform/lang-impl/src/com/intellij/profile/codeInspection/ui/ErrorOptionsProvider.java
index 9e2a4c3593f9..41efb0477c82 100644
--- a/platform/lang-impl/src/com/intellij/profile/codeInspection/ui/ErrorOptionsProvider.java
+++ b/platform/lang-impl/src/com/intellij/profile/codeInspection/ui/ErrorOptionsProvider.java
@@ -22,5 +22,14 @@ package com.intellij.profile.codeInspection.ui;
 
 import com.intellij.openapi.options.UnnamedConfigurable;
 
+/**
+ * Register implementation of this interface in the plugin.xml:
+ * <p/>
+ * &lt;extensions defaultExtensionNs="com.intellij"&gt;<br>
+ * &nbsp;&nbsp;&lt;errorOptionsProvider instance="class-name"/&gt;<br>
+ * &lt;/extensions&gt;
+ * <p>
+ * A new instance of the specified class will be created each time then the Settings dialog is opened
+ */
 public interface ErrorOptionsProvider extends UnnamedConfigurable {
 }
\ No newline at end of file
diff --git a/platform/platform-api/src/com/intellij/openapi/options/ConfigurableProvider.java b/platform/platform-api/src/com/intellij/openapi/options/ConfigurableProvider.java
index 67c1ebed3d94..5a71ffa73050 100644
--- a/platform/platform-api/src/com/intellij/openapi/options/ConfigurableProvider.java
+++ b/platform/platform-api/src/com/intellij/openapi/options/ConfigurableProvider.java
@@ -18,6 +18,10 @@ package com.intellij.openapi.options;
 import org.jetbrains.annotations.Nullable;
 
 /**
+ * Register implementation of this class as {@code projectConfigurable} or {@code applicationConfigurable} extension to provide items for
+ * "Project Settings" and "IDE Settings" groups correspondingly in the "Settings" dialog
+ *
+ * @see Configurable
  * @author nik
  */
 public abstract class ConfigurableProvider {
diff --git a/platform/platform-impl/src/com/intellij/ide/GeneralSettingsConfigurable.java b/platform/platform-impl/src/com/intellij/ide/GeneralSettingsConfigurable.java
index 73dd400a10ab..4b13600db805 100644
--- a/platform/platform-impl/src/com/intellij/ide/GeneralSettingsConfigurable.java
+++ b/platform/platform-impl/src/com/intellij/ide/GeneralSettingsConfigurable.java
@@ -27,6 +27,15 @@ import javax.swing.event.ChangeListener;
 import java.awt.*;
 import java.util.List;
 
+/**
+ * To provide an additional settings editor register implementation of {@link com.intellij.openapi.options.SearchableConfigurable} in the plugin.xml:
+ * <p/>
+ * &lt;extensions defaultExtensionNs="com.intellij"&gt;<br>
+ * &nbsp;&nbsp;&lt;generalOptionsProvider instance="class-name"/&gt;<br>
+ * &lt;/extensions&gt;
+ * <p>
+ * A new instance of the specified class will be created each time then the Settings dialog is opened
+ */
 public class GeneralSettingsConfigurable extends CompositeConfigurable<SearchableConfigurable> implements SearchableConfigurable {
   private static ExtensionPointName<GeneralSettingsConfigurableEP> EP_NAME = ExtensionPointName.create("com.intellij.generalOptionsProvider");
   
diff --git a/platform/platform-impl/src/com/intellij/openapi/options/AbstractConfigurableEP.java b/platform/platform-impl/src/com/intellij/openapi/options/AbstractConfigurableEP.java
index 9701b20d6e3d..50924d88a665 100644
--- a/platform/platform-impl/src/com/intellij/openapi/options/AbstractConfigurableEP.java
+++ b/platform/platform-impl/src/com/intellij/openapi/options/AbstractConfigurableEP.java
@@ -34,7 +34,7 @@ public class AbstractConfigurableEP<T extends UnnamedConfigurable> extends Abstr
   public String instanceClass;
 
   /**
-   * @deprecated
+   * @deprecated use '{@link #instanceClass instance}' attribute instead
    */
   @Attribute("implementation")
   public String implementationClass;
diff --git a/platform/platform-impl/src/com/intellij/openapi/options/ConfigurableEP.java b/platform/platform-impl/src/com/intellij/openapi/options/ConfigurableEP.java
index e45cf23d8cab..a9e4094473d6 100644
--- a/platform/platform-impl/src/com/intellij/openapi/options/ConfigurableEP.java
+++ b/platform/platform-impl/src/com/intellij/openapi/options/ConfigurableEP.java
@@ -30,6 +30,9 @@ import org.picocontainer.PicoContainer;
  * @author nik
  */
 public class ConfigurableEP extends AbstractExtensionPointBean {
+  /**
+   * @deprecated use '{@link #instanceClass instance}' or '{@link #providerClass provider}' attribute instead
+   */
   @Attribute("implementation")
   public String implementationClass;
   @Attribute("instance")