diff --git a/platform/core-api/src/com/intellij/ide/plugins/IdeaPluginDescriptor.java b/platform/core-api/src/com/intellij/ide/plugins/IdeaPluginDescriptor.java
index 0a6fb2546b45..36f9cea83272 100644
--- a/platform/core-api/src/com/intellij/ide/plugins/IdeaPluginDescriptor.java
+++ b/platform/core-api/src/com/intellij/ide/plugins/IdeaPluginDescriptor.java
@@ -13,7 +13,8 @@ import java.util.Date;
 import java.util.List;
 
 /**
- * @author max
+ * Describes a plugin which may be installed into IntelliJ-based IDE. Use {@link com.intellij.ide.plugins.PluginManager#getPlugin(PluginId)}
+ * to get a descriptor by a plugin ID and {@link com.intellij.ide.plugins.PluginManagerCore#getPlugins()} to get all plugins.
  */
 public interface IdeaPluginDescriptor extends PluginDescriptor {
   File getPath();
diff --git a/platform/core-impl/src/com/intellij/ide/plugins/PluginManagerCore.java b/platform/core-impl/src/com/intellij/ide/plugins/PluginManagerCore.java
index 727871909ade..4509bca85bc5 100644
--- a/platform/core-impl/src/com/intellij/ide/plugins/PluginManagerCore.java
+++ b/platform/core-impl/src/com/intellij/ide/plugins/PluginManagerCore.java
@@ -121,7 +121,11 @@ public class PluginManagerCore {
   private static final List<Runnable> ourDisabledPluginsListeners = new CopyOnWriteArrayList<>();
 
   /**
-   * do not call this method during bootstrap, should be called in a copy of PluginManager, loaded by IdeaClassLoader
+   * Returns list of all available plugin descriptors (bundled and custom, include disabled ones). Use {@link #getLoadedPlugins(StartupProgress)}
+   * if you need to get loaded plugins only.
+   *
+   * <p>
+   * Do not call this method during bootstrap, should be called in a copy of PluginManager, loaded by PluginClassLoader.
    */
   @NotNull
   public static IdeaPluginDescriptor[] getPlugins() {
diff --git a/platform/extensions/src/com/intellij/openapi/extensions/PluginId.java b/platform/extensions/src/com/intellij/openapi/extensions/PluginId.java
index b83036b7e97e..320ea5414b76 100644
--- a/platform/extensions/src/com/intellij/openapi/extensions/PluginId.java
+++ b/platform/extensions/src/com/intellij/openapi/extensions/PluginId.java
@@ -23,7 +23,7 @@ import org.jetbrains.annotations.Nullable;
 import java.util.Map;
 
 /**
- * @author max
+ * Represents an ID of a plugin. A full descriptor of the plugin may be obtained via {@link com.intellij.ide.plugins.PluginManager#getPlugin(PluginId)} method.
  */
 public class PluginId implements Comparable<PluginId> {
   public static final PluginId[] EMPTY_ARRAY = new PluginId[0];