Summary

Use @implSpec tags in SimpleJavaFileObject and JavaFileManager to convey the behavior of "default" methods.

Problem

Typical case of wanting to specify "this particular method does X" in contrast to the general contract of a method.

Solution

Use @implSpec tags to convey the distinction.

Specification

diff --git a/src/java.compiler/share/classes/javax/tools/JavaFileManager.java b/src/java.compiler/share/classes/javax/tools/JavaFileManager.java
index a66ed5f6757..327064b5a52 100644
--- a/src/java.compiler/share/classes/javax/tools/JavaFileManager.java
+++ b/src/java.compiler/share/classes/javax/tools/JavaFileManager.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -165,7 +165,7 @@ interface Location {
          * The result of this method is undefined if this is an output
          * location.
          *
-         * @implNote This implementation returns true if the name includes
+         * @implSpec This implementation returns true if the name includes
          * the word "MODULE".
          *
          * @return true if this location is expected to contain modules
diff --git a/src/java.compiler/share/classes/javax/tools/SimpleJavaFileObject.java b/src/java.compiler/share/classes/javax/tools/SimpleJavaFileObject.java
index 1f37797397e..521a1ac2d65 100644
--- a/src/java.compiler/share/classes/javax/tools/SimpleJavaFileObject.java
+++ b/src/java.compiler/share/classes/javax/tools/SimpleJavaFileObject.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -79,10 +79,10 @@ public String getName() {
     }

     /**
+     * {@inheritDoc FileObject}
+     * @implSpec
      * This implementation always throws {@linkplain
-     * UnsupportedOperationException}.  Subclasses can change this
-     * behavior as long as the contract of {@link FileObject} is
-     * obeyed.
+     * UnsupportedOperationException}.
      */
     @Override
     public InputStream openInputStream() throws IOException {
@@ -90,10 +90,10 @@ public InputStream openInputStream() throws IOException {
     }

     /**
+     * {@inheritDoc FileObject}
+     * @implSpec
      * This implementation always throws {@linkplain
-     * UnsupportedOperationException}.  Subclasses can change this
-     * behavior as long as the contract of {@link FileObject} is
-     * obeyed.
+     * UnsupportedOperationException}.
      */
     @Override
     public OutputStream openOutputStream() throws IOException {
@@ -101,9 +101,9 @@ public OutputStream openOutputStream() throws IOException {
     }

     /**
-     * Wraps the result of {@linkplain #getCharContent} in a Reader.
-     * Subclasses can change this behavior as long as the contract of
-     * {@link FileObject} is obeyed.
+     * {@inheritDoc FileObject}
+     * @implSpec
+     * This implementation wraps the result of {@linkplain #getCharContent} in a Reader.
      *
      * @param  ignoreEncodingErrors {@inheritDoc}
      * @return a Reader wrapping the result of getCharContent
@@ -123,10 +123,10 @@ public Reader openReader(boolean ignoreEncodingErrors) throws IOException {
     }

     /**
+     * {@inheritDoc FileObject}
+     * @implSpec
      * This implementation always throws {@linkplain
-     * UnsupportedOperationException}.  Subclasses can change this
-     * behavior as long as the contract of {@link FileObject} is
-     * obeyed.
+     * UnsupportedOperationException}.
      */
     @Override
     public CharSequence getCharContent(boolean ignoreEncodingErrors) throws IOException {
@@ -134,9 +134,9 @@ public CharSequence getCharContent(boolean ignoreEncodingErrors) throws IOExcept
     }

     /**
-     * Wraps the result of openOutputStream in a Writer.  Subclasses
-     * can change this behavior as long as the contract of {@link
-     * FileObject} is obeyed.
+     * {@inheritDoc FileObject}
+     * @implSpec
+     * This implementation wraps the result of openOutputStream in a Writer.
      *
      * @return a Writer wrapping the result of openOutputStream
      * @throws IllegalStateException {@inheritDoc}
@@ -149,9 +149,9 @@ public Writer openWriter() throws IOException {
     }

     /**
-     * This implementation returns {@code 0L}.  Subclasses can change
-     * this behavior as long as the contract of {@link FileObject} is
-     * obeyed.
+     * {@inheritDoc FileObject}
+     * @implSpec
+     * This implementation returns {@code 0L}.
      *
      * @return {@code 0L}
      */
@@ -161,9 +161,9 @@ public long getLastModified() {
     }

     /**
-     * This implementation does nothing.  Subclasses can change this
-     * behavior as long as the contract of {@link FileObject} is
-     * obeyed.
+     * {@inheritDoc FileObject}
+     * @implSpec
+     * This implementation does nothing.
      *
      * @return {@code false}
      */
@@ -181,6 +181,8 @@ public Kind getKind() {
     }

     /**
+     * {@inheritDoc JavaFileObject}
+     * @implSpec
      * This implementation compares the path of its URI to the given
      * simple name.  This method returns true if the given kind is
      * equal to the kind of this object, and if the path is equal to
@@ -190,9 +192,6 @@ public Kind getKind() {
      * <p>This method calls {@link #getKind} and {@link #toUri} and
      * does not access the fields {@link #uri} and {@link #kind}
      * directly.
-     *
-     * <p>Subclasses can change this behavior as long as the contract
-     * of {@link JavaFileObject} is obeyed.
      */
     @Override
     public boolean isNameCompatible(String simpleName, Kind kind) {
@@ -203,17 +202,17 @@ public boolean isNameCompatible(String simpleName, Kind kind) {
     }

     /**
-     * This implementation returns {@code null}.  Subclasses can
-     * change this behavior as long as the contract of
-     * {@link JavaFileObject} is obeyed.
+     * {@inheritDoc JavaFileObject}
+     * @implSpec
+     * This implementation returns {@code null}.
      */
     @Override
     public NestingKind getNestingKind() { return null; }

     /**
-     * This implementation returns {@code null}.  Subclasses can
-     * change this behavior as long as the contract of
-     * {@link JavaFileObject} is obeyed.
+     * {@inheritDoc JavaFileObject}
+     * @implSpec
+     * This implementation returns {@code null}.
      */
     @Override
     public Modifier getAccessLevel()  { return null; }