javadocs and deprecation

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 {

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

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 {

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

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 {

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> {

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

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 {

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");
   

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;

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")