8246280: Refine API to model sealed classes and interfaces in javax.lang.model

Reviewed-by: vromero, jjg

Author: jddarcy

src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java

@@ -255,13 +255,17 @@ default List<? extends RecordComponentElement> getRecordComponents() {
     /**
      * Returns the permitted classes of this class or interface
      * element in declaration order.
+     * Note that for an interface, permitted subclasses and
+     * subinterfaces can be returned.
      *
      * @implSpec The default implementations of this method returns an
      * empty and unmodifiable list.
      *
      * @return the permitted classes, or an empty list if there are none
      *
      * @since 17
+     * @jls 8.1.6 Permitted Direct Subclasses
+     * @jls 9.1.4 Permitted Direct Subclasses and Subinterfaces
      */
     default List<? extends TypeMirror> getPermittedSubclasses() {
         return List.of();