diff --git a/platform/build-scripts/groovy/org/jetbrains/intellij/build/impl/BaseLayoutSpec.groovy b/platform/build-scripts/groovy/org/jetbrains/intellij/build/impl/BaseLayoutSpec.groovy
index 76d5bf96cfb3..7c9016d55725 100644
--- a/platform/build-scripts/groovy/org/jetbrains/intellij/build/impl/BaseLayoutSpec.groovy
+++ b/platform/build-scripts/groovy/org/jetbrains/intellij/build/impl/BaseLayoutSpec.groovy
@@ -31,7 +31,7 @@ class BaseLayoutSpec {
    * 'Runtime' to be copied to the 'lib' directory of the plugin.
    *
    * @param relativeJarPath target JAR path relative to 'lib' directory of the plugin; different modules may be packed into the same JAR,
-   * but don't use this for new plugins; this parameter is temporary added to keep layout of old plugins.
+   * but <strong>don't use this for new plugins</strong>; this parameter is temporary added to keep layout of old plugins.
    * @param localizableResourcesInCommonJar if {@code true} the translatable resources from the module (messages, inspection descriptions, etc) will be
    * placed into a separate 'resources_en.jar'. <strong>Do not use this for new plugins, this parameter is temporary added to keep layout of old plugins</strong>.
    */
diff --git a/platform/build-scripts/groovy/org/jetbrains/intellij/build/impl/PluginLayout.groovy b/platform/build-scripts/groovy/org/jetbrains/intellij/build/impl/PluginLayout.groovy
index 7bc8c7646730..31537047e51b 100644
--- a/platform/build-scripts/groovy/org/jetbrains/intellij/build/impl/PluginLayout.groovy
+++ b/platform/build-scripts/groovy/org/jetbrains/intellij/build/impl/PluginLayout.groovy
@@ -75,15 +75,18 @@ class PluginLayout extends BaseLayout {
   static class PluginLayoutSpec extends BaseLayoutSpec {
     private final PluginLayout layout
     /**
-     * Name of the directory (under 'plugins' directory) where the plugin should be placed
+     * Custom name of the directory (under 'plugins' directory) where the plugin should be placed. By default the main module name is used.
+     * <strong>Don't set this property for new plugins</strong>; it is temporary added to keep layout of old plugins unchanged.
      */
     String directoryName
     /**
-     * Name of the main plugin JAR file
+     * Custom name of the main plugin JAR file. By default the main module name with 'jar' extension is used.
+     * <strong>Don't set this property for new plugins</strong>; it is temporary added to keep layout of old plugins unchanged.
      */
     String mainJarName
     /**
-     * Version of the plugin if it differs from the global build number
+     * Version of the plugin if it differs from the global build number.
+     * <strong>Don't set this property for new plugins</strong>; it is temporary added to keep versioning scheme for some old plugins.
      */
     String version