diff --git a/platform/platform-api/src/com/intellij/openapi/ui/panel/ComponentPanelBuilder.java b/platform/platform-api/src/com/intellij/openapi/ui/panel/ComponentPanelBuilder.java
index 3b2cd8bad435..12a08f6c1b56 100644
--- a/platform/platform-api/src/com/intellij/openapi/ui/panel/ComponentPanelBuilder.java
+++ b/platform/platform-api/src/com/intellij/openapi/ui/panel/ComponentPanelBuilder.java
@@ -83,7 +83,15 @@ public class ComponentPanelBuilder implements GridBagPanelBuilder {
     return this;
   }
 
-
+  /**
+   * Sets optional help tooltip link and link action.
+   *
+   * @param linkText help tooltip link text.
+   *
+   * @param action help tooltip link action.
+   *
+   * @return <code>this</code>
+   */
   public ComponentPanelBuilder withTooltipLink(@NotNull String linkText, @NotNull Runnable action) {
     myHTLinkText = linkText;
     myHTAction = action;
diff --git a/platform/platform-api/src/com/intellij/util/ui/UI.java b/platform/platform-api/src/com/intellij/util/ui/UI.java
index f4b6431a80c7..d86408fce4a8 100644
--- a/platform/platform-api/src/com/intellij/util/ui/UI.java
+++ b/platform/platform-api/src/com/intellij/util/ui/UI.java
@@ -12,6 +12,39 @@ import javax.swing.*;
  */
 public class UI extends JBUI {
 
+  /**
+   * <p>Factory class for creating panels of components. There are two different types of panels.</p>
+   *
+   * <p>1) Component panel. It's essentially a <code>JComponent</code> that can be decorated with:
+   * <ul>
+   *   <li>&nbsp;a label that's located on the right of the component</li>
+   *   <li>&nbsp;a help context label that's located on the left or below of the component</li>
+   *   <li>&nbsp;an icon with a question mark that show a popup with more information which is show on the left</li>
+   * </ul>
+   * For more information see {@link ComponentPanelBuilder}</p>
+   *
+   * <p>2) ProgressBar panel. A panel containing <code>JProgressBar</code> that has specific layout
+   * which is different from an arbitrary component panel. A progress bar panel can contain following items:
+   * <ul>
+   *   <li>&nbsp;a label that' located above or on the left of the progress bar</li>
+   *   <li>&nbsp;a comment label that's located below the progress bar</li>
+   *   <li>&nbsp;Cancel, Play, Pause buttons with assignable actions</li>
+   * </ul>
+   * For more information see {@link ProgressPanelBuilder}</p>
+   *
+   * <p>Either of the mentioned panels can be grouped together in a grid. I.e. it's possible to create a grid of
+   * panels see {@link #grid()}.
+   * When using grid internal implementation makes sure all labels (if the are placed on the left) are located
+   * in the leftmost column and components/progress bars are in the second column expanding horizontally.
+   * </p>
+   *
+   * <p>{@link PanelGridBuilder} has convenient {@link PanelGridBuilder#expandVertically()} method that allows rows to expand
+   * vertically when the grid is resized. By default all rows stick to the top of the grid and all available empty space is
+   * expanded below rows.
+   * </p>
+   *
+   * <p>For concrete examples look <code>ComponentPanelTestAction</code> test action and class.</p>
+   */
   public static class PanelFactory {
 
     /**