IDEA-132304 Update com.intellij.openapi.options.ConfigurableEP java doc

platform/platform-api/src/com/intellij/openapi/options/Configurable.java

@@ -59,12 +59,12 @@ import org.jetbrains.annotations.Nullable;
  *   <dd>This attribute specifies the setting name visible to users.
  *   If the display name is not set, a configurable component will be instantiated to retrieve its name dynamically.
  *   This causes a loading of plugin classes and increases the delay before showing the settings dialog.
- *   It is highly recommended specifiyng the display name in XML to improve UI responsiveness.</dd>
+ *   It is highly recommended specifying the display name in XML to improve UI responsiveness.</dd>
  *   <dt>{@code key} and {@code bundle}</dt>
  *   <dd>These attributes specify the display name too, if the specified key is declared in the specified resource bundle.</dd>
  *   <dt>{@code id}</dt>
  *   <dd>This attribute specifies the {@link SearchableConfigurable#getId() unique identifier}
- *   for the configurable component.  It is also recommended specifiyng the identifier in XML.</dd>
+ *   for the configurable component.  It is also recommended specifying the identifier in XML.</dd>
  *   <dt>{@code parentId}</dt>
  *   <dd>This attribute is used to create a hierarchy of settings.
  *   If it is set, the configurable component will be a child of the specified parent component.</dd>
@@ -76,7 +76,7 @@ import org.jetbrains.annotations.Nullable;
  *     <dt>ROOT {@code groupId="root"}</dt>
  *     <dd>This is the invisible root group that contains all other groups.
  *     Usually, you should not place your settings here.</dd>
- *     <dt>Appearance &amp; Behavior {@code groupId="appearance"}</dt>
+ *     <dt>Appearance & Behavior {@code groupId="appearance"}</dt>
  *     <dd>This group contains settings to personalize IDE appearance and behavior:
  *     change themes and font size, tune the keymap, and configure plugins and system settings,
  *     such as password policies, HTTP proxy, updates and more.</dd>
@@ -92,7 +92,7 @@ import org.jetbrains.annotations.Nullable;
  *     <dt>Build Tools {@code groupId="build.tools"}</dt>
  *     <dd>This is subgroup of the group above. Here you can configure your project integration
  *     with the different build tools, such as Maven, Gradle, or Gant.</dd>
- *     <dt>Languages &amp; Frameworks {@code groupId="language"}</dt>
+ *     <dt>Languages & Frameworks {@code groupId="language"}</dt>
  *     <dd>This group is intended to configure the settings related to specific frameworks and technologies used in your project.</dd>
  *     <dt>Tools {@code groupId="tools"}</dt>
  *     <dd>This group contains settings to configure integration with third-party applications,

platform/platform-api/src/com/intellij/openapi/options/ConfigurableEP.java

@@ -33,6 +33,8 @@ import org.picocontainer.PicoContainer;
 import java.util.ResourceBundle;
 
 /**
+ * Declares a named component that enables to configure settings.
+ *
  * @author nik
  * @see Configurable
  */
@@ -40,12 +42,27 @@ import java.util.ResourceBundle;
 public class ConfigurableEP<T extends UnnamedConfigurable> extends AbstractExtensionPointBean {
   private static final Logger LOG = Logger.getInstance("#com.intellij.openapi.options.ConfigurableEP");
 
+  /**
+   * This attribute specifies the setting name visible to users.
+   * It has precedence over the pair of attributes {@link #key}-{@link #bundle}.
+   * If the display name is not set, a configurable component will be instantiated to retrieve its name dynamically.
+   * This causes a loading of plugin classes and increases the delay before showing the settings dialog.
+   * It is highly recommended specifying the display name in XML to improve UI responsiveness.
+   */
   @Attribute("displayName")
   public String displayName;
 
+  /**
+   * This attribute specifies the resource key in the specified {@link #bundle}.
+   * This is another way to specify the {@link #displayName display name}.
+   */
   @Attribute("key")
   public String key;
 
+  /**
+   * This attribute specifies the resource bundle that contains the specified {@link #key}.
+   * This is another way to specify the {@link #displayName display name}.
+   */
   @Attribute("bundle")
   public String bundle;
 
@@ -70,18 +87,27 @@ public class ConfigurableEP<T extends UnnamedConfigurable> extends AbstractExten
   public ConfigurableEP[] children;
 
   /**
-   * Extension point of ConfigurableEP type to calculate children
+   * This attribute specifies a name of the extension point of {@code ConfigurableEP} type that will be used to calculate children.
+   *
+   * @see #dynamic
    */
   @Attribute("childrenEPName")
   public String childrenEPName;
 
   /**
-   * Indicates that configurable has dynamically calculated children.
-   * {@link com.intellij.openapi.options.Configurable.Composite#getConfigurables()} will be called for such configurables.
+   * This attribute states that a custom configurable component implements the {@link Configurable.Composite} interface
+   * and its children are dynamically calculated by calling the {@link Configurable.Composite#getConfigurables()} method.
+   * It is needed to improve performance, because we do not want to load any additional classes during the building a setting tree.
    */
   @Attribute("dynamic")
   public boolean dynamic;
 
+  /**
+   * This attribute is used to create a hierarchy of settings.
+   * If it is set, the configurable component will be a child of the specified parent component.
+   *
+   * @see #groupId
+   */
   @Attribute("parentId")
   public String parentId;
 
@@ -94,16 +120,66 @@ public class ConfigurableEP<T extends UnnamedConfigurable> extends AbstractExten
     return children;
   }
 
+  /**
+   * This attribute specifies the {@link SearchableConfigurable#getId() unique identifier} of the configurable component.
+   * It is also recommended specifying the identifier in XML to improve UI responsiveness.
+   */
   @Attribute("id")
   public String id;
 
+  /**
+   * This attribute specifies a top-level group, which the configurable component belongs to.
+   * If this attribute is not set, the configurable component will be added to the Other Settings group.
+   * The following groups are supported:
+   * <dl>
+   * <dt>ROOT {@code groupId="root"}</dt>
+   * <dd>This is the invisible root group that contains all other groups.
+   * Usually, you should not place your settings here.</dd>
+   * <dt>Appearance & Behavior {@code groupId="appearance"}</dt>
+   * <dd>This group contains settings to personalize IDE appearance and behavior:
+   * change themes and font size, tune the keymap, and configure plugins and system settings,
+   * such as password policies, HTTP proxy, updates and more.</dd>
+   * <dt>Editor {@code groupId="editor"}</dt>
+   * <dd>This group contains settings to personalize source code appearance by changing fonts,
+   * highlighting styles, indents, etc.  Here you can customize the editor from line numbers,
+   * caret placement and tabs to source code inspections, setting up templates and file encodings.</dd>
+   * <dt>Default Project / Project Settings {@code groupId="project"}</dt>
+   * <dd>This group is intended to store some project-related settings, but now it is rarely used.</dd>
+   * <dt>Build, Execution, Deployment {@code groupId="build"}</dt>
+   * <dd>This group contains settings to configure you project integration with the different build tools,
+   * modify the default compiler settings, manage server access configurations, customize the debugger behavior, etc.</dd>
+   * <dt>Build Tools {@code groupId="build.tools"}</dt>
+   * <dd>This is subgroup of the group above. Here you can configure your project integration
+   * with the different build tools, such as Maven, Gradle, or Gant.</dd>
+   * <dt>Languages & Frameworks {@code groupId="language"}</dt>
+   * <dd>This group is intended to configure the settings related to specific frameworks and technologies used in your project.</dd>
+   * <dt>Tools {@code groupId="tools"}</dt>
+   * <dd>This group contains settings to configure integration with third-party applications,
+   * specify the SSH Terminal connection settings, manage server certificates and tasks, configure diagrams layout, etc.</dd>
+   * <dt>Other Settings {@code groupId="other"}</dt>
+   * <dd>This group contains settings that are related to non-bundled custom plugins and are not assigned to any other category.</dd>
+   * </dl>
+   * This attribute should not be used together with the {@link #parentId} attribute, which has precedence.
+   * Currently, it is possible to specify a group identifier in the {@link #parentId} attribute.
+   */
   @Attribute("groupId")
   public String groupId;
 
+  /**
+   * This attribute specifies the weight of a configurable component within a group or a parent configurable component.
+   * The default weight is {@code 0}. If one child in a group or a parent configurable component has non-zero weight,
+   * all children will be sorted descending by their weight. And if the weights are equal,
+   * the components will be sorted ascending by their display name.
+   */
   @Attribute("groupWeight")
   public int groupWeight;
 
-  /** Marks project level configurables that do not apply to the default project. */
+  /**
+   * This attribute is applicable to the {@code projectConfigurable} extension only.
+   * If it is set to {@code true}, the corresponding project settings will be shown for a real project only,
+   * not for the {@link com.intellij.openapi.project.ProjectManager#getDefaultProject() template project},
+   * which provides default settings for all the new projects.
+   */
   @Attribute("nonDefaultProject")
   public boolean nonDefaultProject;
 
@@ -114,10 +190,32 @@ public class ConfigurableEP<T extends UnnamedConfigurable> extends AbstractExten
   /**
    * @deprecated use '{@link #instanceClass instance}' or '{@link #providerClass provider}' attribute instead
    */
+  @Deprecated
   @Attribute("implementation")
   public String implementationClass;
+
+  /**
+   * This attribute specifies a qualified name of a custom implementation of this interface.
+   * The constructor will be determined automatically from the tag name:
+   * <br>{@code <extensions defaultExtensionNs="com.intellij">}
+   * <br>{@code &nbsp;&nbsp;&nbsp;&nbsp;<projectConfigurable instance="fully.qualified.class.name"/>}
+   * <br>{@code </extensions>}
+   *
+   * @see #providerClass provider
+   */
   @Attribute("instance")
   public String instanceClass;
+
+  /**
+   * This attribute can be used instead of the {@link #instanceClass instance} attribute.
+   * It specifies a qualified name of a custom implementation of the {@link ConfigurableProvider} interface,
+   * which provides another way to create a configurable component:
+   * <br>{@code <extensions defaultExtensionNs="com.intellij">}
+   * <br>{@code &nbsp;&nbsp;&nbsp;&nbsp;<projectConfigurable provider="fully.qualified.class.name"/>}
+   * <br>{@code </extensions>}
+   *
+   * @see #instanceClass instance
+   */
   @Attribute("provider")
   public String providerClass;