6878792: Sample provided in javax.swing.JLayer class description is not usable

Reviewed-by: rupashka

src/share/classes/javax/swing/JLayer.java

@@ -56,28 +56,70 @@ import java.security.PrivilegedAction;
  * {@code JLayer} is a good solution if you only need to do custom painting
  * over compound component or catch input events from its subcomponents.
  * <pre>
- *         // create a component to be decorated with the layer
- *        JPanel panel = new JPanel();
- *        panel.add(new JButton("JButton"));
+ * import javax.swing.*;
+ * import javax.swing.plaf.LayerUI;
+ * import java.awt.*;
+ *
+ * public class JLayerSample {
+ *
+ *     private static JLayer&lt;JComponent&gt; createLayer() {
  *         // This custom layerUI will fill the layer with translucent green
  *         // and print out all mouseMotion events generated within its borders
- *        LayerUI&lt;JPanel&gt; layerUI = new LayerUI&lt;JPanel&gt;() {
- *            public void paint(Graphics g, JCompo  nent c) {
+ *         LayerUI&lt;JComponent&gt; layerUI = new LayerUI&lt;JComponent&gt;() {
+ *
+ *             public void paint(Graphics g, JComponent c) {
  *                 // paint the layer as is
  *                 super.paint(g, c);
  *                 // fill it with the translucent green
  *                 g.setColor(new Color(0, 128, 0, 128));
  *                 g.fillRect(0, 0, c.getWidth(), c.getHeight());
  *             }
+ *
+ *             public void installUI(JComponent c) {
+ *                 super.installUI(c);
+ *                 // enable mouse motion events for the layer's subcomponents
+ *                 ((JLayer) c).setLayerEventMask(AWTEvent.MOUSE_MOTION_EVENT_MASK);
+ *             }
+ *
+ *             public void uninstallUI(JComponent c) {
+ *                 super.uninstallUI(c);
+ *                 // reset the layer event mask
+ *                 ((JLayer) c).setLayerEventMask(0);
+ *             }
+ *
  *             // overridden method which catches MouseMotion events
- *            public void eventDispatched(AWTEvent e, JLayer&lt;JPanel&gt; l) {
+ *             public void eventDispatched(AWTEvent e, JLayer&lt;? extends JComponent&gt; l) {
  *                 System.out.println("AWTEvent detected: " + e);
  *             }
  *         };
+ *         // create a component to be decorated with the layer
+ *         JPanel panel = new JPanel();
+ *         panel.add(new JButton("JButton"));
+ *
  *         // create the layer for the panel using our custom layerUI
- *        JLayer&lt;JPanel&gt; layer = new JLayer&lt;JPanel&gt;(panel, layerUI);
+ *         return new JLayer&lt;JComponent&gt;(panel, layerUI);
+ *     }
+ *
+ *     private static void createAndShowGUI() {
+ *         final JFrame frame = new JFrame();
+ *         frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
+ *
  *         // work with the layer as with any other Swing component
- *        frame.add(layer);
+ *         frame.add(createLayer());
+ *
+ *         frame.setSize(200, 200);
+ *         frame.setLocationRelativeTo(null);
+ *         frame.setVisible(true);
+ *     }
+ *
+ *     public static void main(String[] args) throws Exception {
+ *         SwingUtilities.invokeAndWait(new Runnable() {
+ *             public void run() {
+ *                 createAndShowGUI();
+ *             }
+ *         });
+ *     }
+ * }
  * </pre>
  *
  * <b>Note:</b> {@code JLayer} doesn't support the following methods: