--- a/jdk/src/share/classes/java/awt/Paint.java	Mon Mar 31 15:56:12 2008 +0400
+++ b/jdk/src/share/classes/java/awt/Paint.java	Fri Apr 04 20:20:16 2008 +0400
@@ -46,42 +46,58 @@
  * @see GradientPaint
  * @see TexturePaint
  * @see Graphics2D#setPaint
+ * @version 1.36, 06/05/07
  */
 
 public interface Paint extends Transparency {
     /**
      * Creates and returns a {@link PaintContext} used to
      * generate the color pattern.
-     * Since the ColorModel argument to createContext is only a
-     * hint, implementations of Paint should accept a null argument
-     * for ColorModel.  Note that if the application does not
-     * prefer a specific ColorModel, the null ColorModel argument
-     * will give the Paint implementation full leeway in using the
-     * most efficient ColorModel it prefers for its raster processing.
-     * <p>
-     * Since the API documentation was not specific about this in
-     * releases before 1.4, there may be implementations of
-     * <code>Paint</code> that do not accept a null
-     * <code>ColorModel</code> argument.
-     * If a developer is writing code which passes a null
-     * <code>ColorModel</code> argument to the
-     * <code>createContext</code> method of <code>Paint</code>
-     * objects from arbitrary sources it would be wise to code defensively
-     * by manufacturing a non-null <code>ColorModel</code> for those
-     * objects which throw a <code>NullPointerException</code>.
-     * @param cm the {@link ColorModel} that receives the
-     * <code>Paint</code> data. This is used only as a hint.
+     * The arguments to this method convey additional information
+     * about the rendering operation that may be
+     * used or ignored on various implementations of the {@code Paint} interface.
+     * A caller must pass non-{@code null} values for all of the arguments
+     * except for the {@code ColorModel} argument which may be {@code null} to
+     * indicate that no specific {@code ColorModel} type is preferred.
+     * Implementations of the {@code Paint} interface are allowed to use or ignore
+     * any of the arguments as makes sense for their function, and are
+     * not constrained to use the specified {@code ColorModel} for the returned
+     * {@code PaintContext}, even if it is not {@code null}.
+     * Implementations are allowed to throw {@code NullPointerException} for
+     * any {@code null} argument other than the {@code ColorModel} argument,
+     * but are not required to do so.
+     *
+     * @param cm the preferred {@link ColorModel} which represents the most convenient
+     *           format for the caller to receive the pixel data, or {@code null}
+     *           if there is no preference.
      * @param deviceBounds the device space bounding box
-     *                     of the graphics primitive being rendered
+     *                     of the graphics primitive being rendered.
+     *                     Implementations of the {@code Paint} interface
+     *                     are allowed to throw {@code NullPointerException}
+     *                     for a {@code null} {@code deviceBounds}.
      * @param userBounds the user space bounding box
-     *                     of the graphics primitive being rendered
+     *                   of the graphics primitive being rendered.
+     *                     Implementations of the {@code Paint} interface
+     *                     are allowed to throw {@code NullPointerException}
+     *                     for a {@code null} {@code userBounds}.
      * @param xform the {@link AffineTransform} from user
-     *      space into device space
-     * @param hints the hint that the context object uses to
-     *              choose between rendering alternatives
-     * @return the <code>PaintContext</code> for
-     *              generating color patterns
+     *              space into device space.
+     *                     Implementations of the {@code Paint} interface
+     *                     are allowed to throw {@code NullPointerException}
+     *                     for a {@code null} {@code xform}.
+     * @param hints the set of hints that the context object can use to
+     *              choose between rendering alternatives.
+     *                     Implementations of the {@code Paint} interface
+     *                     are allowed to throw {@code NullPointerException}
+     *                     for a {@code null} {@code hints}.
+     * @return the {@code PaintContext} for
+     *         generating color patterns.
      * @see PaintContext
+     * @see ColorModel
+     * @see Rectangle
+     * @see Rectangle2D
+     * @see AffineTransform
+     * @see RenderingHints
      */
     public PaintContext createContext(ColorModel cm,
                                       Rectangle deviceBounds,