--- old/src/java.base/share/classes/java/lang/Class.java	2018-03-07 12:08:22.000000000 -0800
+++ new/src/java.base/share/classes/java/lang/Class.java	2018-03-07 12:08:21.000000000 -0800
@@ -3830,24 +3830,22 @@
     /**
      * Returns the nest host of the object represented by this {@code Class}.
      *
-     * <p>If there is any error accessing the nest host, or the nest host is
+     * If there is any error accessing the nest host, or the nest host is
      * in any way invalid, then {@code this} is returned.
      *
-     * @apiNote A nest is a set of classes and interfaces (nestmates) that
-     * form an access control context in which each nestmate has access to the
-     * private members of the other nestmates (JVMS 4.7.28).
-     * Nest membership is declared through special attributes in the binary
-     * representation of a class or interface (JVMS 4.1).
+     * <p>
+     * <a id="nestmates">Nest Membership</a>
+     * A <em>nest</em> is a set of classes and interfaces
+     * ({@linkplain #getNestMembers() nestmates}) that
+     * form an access control context in which each nestmate has access to
+     * the private members of the other nestmates (JVMS 4.7.28).
      * The nest host is the class or interface designated to hold the list of
      * classes and interfaces that make up the nest, and to which each of the
      * other nestmates refer.
-     * The source language compiler is responsible for deciding which classes
-     * and interfaces are nestmates. For example, the {@code javac} compiler
-     * places a top-level class or interface into a nest with all of its direct,
-     * and indirect, {@linkplain #getDeclaredClasses() nested classes and interfaces}
-     * (JLS 8).
-     * The top-level {@linkplain #getEnclosingClass() enclosing class or interface}
-     * is designated as the nest host.
+     * A {@linkplain #getEnclosingClass() top-level class or interface} is
+     * typically placed into a nest with all of its direct and indirect
+     * {@linkplain #getDeclaredClasses() nested classes and interfaces}.
+     * The top-level class or interface is designated as the nest host.
      *
      * <p>A class or interface that is not explicitly a member of a nest,
      * is a member of the nest consisting only of itself, and is the
@@ -3856,7 +3854,16 @@
      * @return the nest host of this class, or {@code this} if we cannot
      * obtain a valid nest host
      *
+     * @throws SecurityException
+     *         If a security manager, <i>s</i>, is present and
+     *         the caller's class loader is not the same as or an
+     *         ancestor of the class loader for the current class and
+     *         invocation of {@link SecurityManager#checkPackageAccess
+     *         s.checkPackageAccess()} denies access to the package
+     *         of this class
+     *
      * @since 11
+     * @jvms 4.7.28 and 4.7.29 NestHost and NestMembers attributes
      */
     public Class<?> getNestHost() {
         if (isPrimitive() || isArray()) {
@@ -3878,8 +3885,8 @@
     }
 
     /**
-     * Determines if the given {@code Class} is a nestmate of the
-     * object represented by this {@code Class}. Two classes are nestmates
+     * Determines if the given {@code Class} is a <a href="#nestmates">nestmate</a>
+     * of the object represented by this {@code Class}. Two classes are nestmates
      * if they have the same {@linkplain #getNestHost nest host}.
      *
      * @param  c the class to check
@@ -3919,8 +3926,16 @@
      *
      * @throws LinkageError if there is any problem loading or validating
      * a nest member or its nest host
+     * @throws SecurityException
+     *         If a security manager, <i>s</i>, is present and
+     *         the caller's class loader is not the same as or an
+     *         ancestor of the class loader for the current class and
+     *         invocation of {@link SecurityManager#checkPackageAccess
+     *         s.checkPackageAccess()} denies access to the package
+     *         of this class
      *
      * @since 11
+     * @jvms 4.7.29 NestMembers attribute
      */
     public Class<?>[] getNestMembers() {
         if (isPrimitive() || isArray()) {