Graphics2D.clip specifies incorrectly that a 'null' is a valid value for this method

Summary

Specify that java.awt.Graphics2D.clip(Shape) will throw NullPointerException when passed a null object reference for the parameter when a user clip is currently set.

Problem

Method clip(Shape) of the java.awt.Graphics2D class throws NullPointerException when passed a null object reference for the parameter when a user clip is currently set, but it is not specified in the specification.

Solution

Update the specification to document that NullPointerException will be thrown for null "Shape" object passed to clip() when a user clip is currently set.

Specification

        src/java.desktop/share/classes/java/awt/Graphics.java
                 * supported are {@code Shape} objects that are
                  * obtained via the {@code getClip} method and via
                  * {@code Rectangle} objects.  This method sets the
                  * user clip, which is independent of the clipping associated
                  * with device bounds and window visibility.
            -     * @param clip the {@code Shape} to use to set the clip
            +     * @param clip the {@code Shape} to use to set the clip.
            +     *             Passing {@code null} clears the current {@code clip}.
                  * @see         java.awt.Graphics#getClip()
                  * @see         java.awt.Graphics#clipRect
                  * @see         java.awt.Graphics#setClip(int, int, int, int)
                  * @since       1.1
                  */
                public abstract void setClip(Shape clip);

            src/java.desktop/share/classes/java/awt/Graphics2D.java     

      * transformed with the current {@code Graphics2D}
      * {@code Transform} before being intersected with the current
      * {@code Clip}.  This method is used to make the current
      * {@code Clip} smaller.
      * To make the {@code Clip} larger, use {@code setClip}.
-     * The <i>user clip</i> modified by this method is independent of the
+     * <p>The <i>user clip</i> modified by this method is independent of the
      * clipping associated with device bounds and visibility.  If no clip has
      * previously been set, or if the clip has been cleared using
      * {@link Graphics#setClip(Shape) setClip} with a {@code null}
      * argument, the specified {@code Shape} becomes the new
      * user clip.
+     * <p>Since this method intersects the specified shape
+     * with the current clip, it will throw {@code NullPointerException}
+     * for a {@code null} shape unless the user clip is also {@code null}.
+     * So calling this method with a {@code null} argument is not recommended.
      * @param s the {@code Shape} to be intersected with the current
-     *          {@code Clip}.  If {@code s} is {@code null},
-     *          this method clears the current {@code Clip}.
+     *          {@code Clip}. This method updates the current {@code Clip}.
+     * @throws NullPointerException if {@code s} is {@code null}
+     *         and a user clip is currently set.
      */
      public abstract void clip(Shape s);