7165112: Incomprehensible garbage in doc for RootPaneContainer

Reviewed-by: alexsch

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

@@ -46,9 +46,10 @@ import javax.accessibility.*;
  * <code>java.applet.Applet</code>.  <code>JApplet</code> contains a
  * <code>JRootPane</code> as its only child.  The <code>contentPane</code>
  * should be the parent of any children of the <code>JApplet</code>.
- * As a convenience <code>add</code> and its variants, <code>remove</code> and
- * <code>setLayout</code> have been overridden to forward to the
- * <code>contentPane</code> as necessary. This means you can write:
+ * As a convenience, the {@code add}, {@code remove}, and {@code setLayout}
+ * methods of this class are overridden, so that they delegate calls
+ * to the corresponding methods of the {@code ContentPane}.
+ * For example, you can add a child component to an applet as follows:
  * <pre>
  *       applet.add(child);
  * </pre>

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

@@ -44,9 +44,10 @@ import javax.accessibility.*;
  * as its only child.
  * The {@code contentPane} should be the parent of any children of the
  * {@code JDialog}.
- * As a convenience {@code add} and its variants, {@code remove} and
- * {@code setLayout} have been overridden to forward to the
- * {@code contentPane} as necessary. This means you can write:
+ * As a convenience, the {@code add}, {@code remove}, and {@code setLayout}
+ * methods of this class are overridden, so that they delegate calls
+ * to the corresponding methods of the {@code ContentPane}.
+ * For example, you can add a child component to a dialog as follows:
  * <pre>
  *       dialog.add(child);
  * </pre>

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

@@ -50,9 +50,10 @@ import javax.accessibility.*;
  * as a rule, contain
  * all the non-menu components displayed by the <code>JFrame</code>.
  * This is different from the AWT <code>Frame</code> case.
- * As a conveniance <code>add</code> and its variants, <code>remove</code> and
- * <code>setLayout</code> have been overridden to forward to the
- * <code>contentPane</code> as necessary. This means you can write:
+ * As a convenience, the {@code add}, {@code remove}, and {@code setLayout}
+ * methods of this class are overridden, so that they delegate calls
+ * to the corresponding methods of the {@code ContentPane}.
+ * For example, you can add a child component to a frame as follows:
  * <pre>
  *       frame.add(child);
  * </pre>

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

@@ -63,9 +63,10 @@ import sun.swing.SwingUtilities2;
  * <p>
  * The <code>JInternalFrame</code> content pane
  * is where you add child components.
- * As a conveniance <code>add</code> and its variants, <code>remove</code> and
- * <code>setLayout</code> have been overridden to forward to the
- * <code>contentPane</code> as necessary. This means you can write:
+ * As a convenience, the {@code add}, {@code remove}, and {@code setLayout}
+ * methods of this class are overridden, so that they delegate calls
+ * to the corresponding methods of the {@code ContentPane}.
+ * For example, you can add a child component to an internal frame as follows:
  * <pre>
  *       internalFrame.add(child);
  * </pre>

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

@@ -43,9 +43,10 @@ import javax.accessibility.*;
  * The <code>JWindow</code> component contains a <code>JRootPane</code>
  * as its only child.  The <code>contentPane</code> should be the parent
  * of any children of the <code>JWindow</code>.
- * As a conveniance <code>add</code> and its variants, <code>remove</code> and
- * <code>setLayout</code> have been overridden to forward to the
- * <code>contentPane</code> as necessary. This means you can write:
+ * As a convenience, the {@code add}, {@code remove}, and {@code setLayout}
+ * methods of this class are overridden, so that they delegate calls
+ * to the corresponding methods of the {@code ContentPane}.
+ * For example, you can add a child component to a window as follows:
  * <pre>
  *       window.add(child);
  * </pre>

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

@@ -45,18 +45,18 @@ import java.awt.Container;
  * dropping a component on a RootPaneContainer would be interpreted
  * as <code>frame.getContentPane().add(child)</code>.
  * <p>
- * For conveniance
- * <code>JFrame</code>, <code>JDialog</code>, <code>JWindow</code>,
- * <code>JApplet</code> and <code>JInternalFrame</code>, by default,
- * forward, by default, all calls to the <code>add</code>,
- * <code>remove</code> and <code>setLayout</code> methods, to the
- * <code>contentPane</code>. This means you can call:
+ * As a convenience, the standard classes that implement this interface
+ * (such as {@code JFrame}, {@code JDialog}, {@code JWindow}, {@code JApplet},
+ * and {@code JInternalFrame}) have their {@code add}, {@code remove},
+ * and {@code setLayout} methods overridden, so that they delegate calls
+ * to the corresponding methods of the {@code ContentPane}.
+ * For example, you can add a child component to a frame as follows:
  * <pre>
- * rootPaneContainer.add(component);
+ *       frame.add(child);
  * </pre>
  * instead of:
  * <pre>
- * rootPaneContainer.getContentPane().add(component);
+ *       frame.getContentPane().add(child);
  * </pre>
  * <p>
  * The behavior of the <code>add</code> and