--- a/jdk/src/java.desktop/share/classes/java/awt/HeadlessException.java	Fri Jul 29 11:04:52 2016 +0300
+++ b/jdk/src/java.desktop/share/classes/java/awt/HeadlessException.java	Fri Jul 29 11:08:34 2016 +0300
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2016, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -28,10 +28,14 @@
 /**
  * Thrown when code that is dependent on a keyboard, display, or mouse
  * is called in an environment that does not support a keyboard, display,
- * or mouse.
+ * or mouse. Any code that depends on any of those devices should firstly
+ * ensure their availability using the {@code GraphicsEnvironment.isHeadless()}
+ * method and throw {@code HeadlessException} if the latter returns
+ * {@code true}.
  *
  * @since 1.4
  * @author  Michael Martak
+ * @see GraphicsEnvironment#isHeadless
  */
 public class HeadlessException extends UnsupportedOperationException {
     /*
@@ -40,12 +44,24 @@
     private static final long serialVersionUID = 167183644944358563L;
 
     /**
-     * Constructs new {@code HeadlessException}
+     * Constructs new {@code HeadlessException} with empty message.
+     * For such {@code HeadlessException} the default headless error message
+     * may be auto-generated for some platforms.
+     * The text of the default headless message may depend on
+     * whether the GraphicsEnvironment is in fact headless.
+     * That is, the default headless message is both system and environmentally
+     * dependent.
      */
     public HeadlessException() {}
 
     /**
      * Create a new instance with the specified detailed error message.
+     * For some platforms the default headless error message may be
+     * added at the end of the specified message.
+     * The text of the default headless message may depend on
+     * whether the GraphicsEnvironment is in fact headless.
+     * That is, the default headless message is both system and environmentally
+     * dependent.
      *
      * @param  msg the error message
      */
@@ -54,7 +70,16 @@
     }
 
     /**
-     * {@inheritDoc}
+     * Returns the detail message string of this {@code HeadlessException}.
+     * Depending on the platform the message specified in the constructor may
+     * be followed by the default headless error message.
+     * The text of the default headless message may depend on
+     * whether the GraphicsEnvironment is in fact headless.
+     * That is, the default headless message is both system and environmentally
+     * dependent.
+     *
+     * @return  the detail message string of this {@code HeadlessException}
+     *          instance (which may be {@code null}).
      */
     public String getMessage() {
         String superMessage = super.getMessage();