--- old/src/jdk.internal.vm.ci/share/classes/jdk.vm.ci.hotspot/src/jdk/vm/ci/hotspot/HotSpotNmethod.java	2017-11-02 08:30:12.000000000 +0100
+++ new/src/jdk.internal.vm.ci/share/classes/jdk.vm.ci.hotspot/src/jdk/vm/ci/hotspot/HotSpotNmethod.java	2017-11-02 08:30:11.000000000 +0100
@@ -30,13 +30,10 @@
 import jdk.vm.ci.meta.ResolvedJavaMethod;
 
 /**
- * Implementation of {@link InstalledCode} for code installed as an nmethod. The nmethod stores a
- * weak reference to an instance of this class. This is necessary to keep the nmethod from being
- * unloaded while the associated {@link HotSpotNmethod} instance is alive.
- * <p>
- * Note that there is no (current) way for the reference from an nmethod to a {@link HotSpotNmethod}
- * instance to be anything but weak. This is due to the fact that HotSpot does not treat nmethods as
- * strong GC roots.
+ * Implementation of {@link InstalledCode} for code installed as an nmethod.
+ *
+ * When a {@link HotSpotNmethod} dies, it triggers unloading of the nmethod unless
+ * {@link #isDefault() == true}.
  */
 public class HotSpotNmethod extends HotSpotInstalledCode {
 
@@ -54,6 +51,11 @@
         this.isDefault = isDefault;
     }
 
+    /**
+     * Determines if the nmethod associated with this object is the compiled entry point for
+     * {@link #getMethod()}. If {@code false}, then the nmethod is unloaded when the VM determines
+     * this object has died.
+     */
     public boolean isDefault() {
         return isDefault;
     }