8256993: Clarify Package::isSealed javadoc about package sealing vs s…

…ealed class or interface

Reviewed-by: alanb

src/java.base/share/classes/java/lang/Package.java

@@ -53,7 +53,7 @@
  * {@code Package} is compatible with a particular specification version
  * by using the {@link #isCompatibleWith Package.isCompatibleWith(String)}
  * method. In addition, information about the actual classes that make up the
- * run-time package can be provided when the Package is defined.
+ * run-time package can be provided when the {@code Package} is defined.
  * This information consists of an implementation title, version, and vendor
  * (indicating the supplier of the classes).
  * <p>
@@ -221,7 +221,15 @@ public String getImplementationVendor() {
     /**
      * Returns true if this package is sealed.
      *
+     * @apiNote
+     * <a href="{@docRoot}/../specs/jar/jar.html#package-sealing">Package sealing</a>
+     * has no relationship with {@linkplain Class#isSealed() sealed classes or interfaces}.
+     * Package sealing is specific to JAR files defined for classes in an unnamed module.
+     * See the {@link Package Package} class specification for details
+     * how a {@code Package} is defined as sealed package.
+     *
      * @return true if the package is sealed, false otherwise
+     *
      */
     public boolean isSealed() {
         return module().isNamed() || versionInfo.sealBase != null;
@@ -231,6 +239,13 @@ public boolean isSealed() {
      * Returns true if this package is sealed with respect to the specified
      * code source {@code url}.
      *
+     * @apiNote
+     * <a href="{@docRoot}/../specs/jar/jar.html#package-sealing">Package sealing</a>
+     * has no relationship with {@linkplain Class#isSealed() sealed classes or interfaces}.
+     * Package sealing is specific to JAR files defined for classes in an unnamed module.
+     * See the {@link Package Package} class specification for details
+     * how a {@code Package} is defined as sealed package.
+     *
      * @param  url the code source URL
      * @return true if this package is sealed with respect to the given {@code url}
      */