--- old/src/java.desktop/share/classes/javax/swing/package-info.java	2017-10-27 16:29:27.068316500 +0530
+++ new/src/java.desktop/share/classes/javax/swing/package-info.java	2017-10-27 16:29:25.754258400 +0530
@@ -94,6 +94,17 @@
  * If you modify the model on a separate thread you run the risk of exceptions
  * and possible display corruption.
  * <p>
+ * Another related issue is performing UI actions in a (custom) model listener
+ * callback. This could lead to weird UI rendering issues. This typically
+ * happens since listeners are called in a particular order (either last to
+ * first or first to last in the order of registration), and if the model
+ * listener tries to change the UI before the UI has had a chance to react to
+ * the changes in the underlying model.
+ * In such cases it is recommended to wrap the callback function contents into a
+ * lambda, and invoke it through {@link SwingUtilities.invokeLater} so that any
+ * UI rendering will be done post processing all the model listeners.
+ * </p>
+ * <p>
  * As all events are delivered on the event dispatching thread, care must be
  * taken in event processing. In particular, a long running task, such as
  * network io or computational intensive processing, executed on the event