Summary

Update the spec to emphasize delegation.

Problem

There is concern that the phrase "this file manager" or "this file object" may be confusing in classes whose role is to delegate to an alternate file manager or file object.

Solution

Add a clarifying sentence in the class-level documentation for each class. The grammar of a couple of related sentences is also improved.

Specification

diff --git a/src/java.compiler/share/classes/javax/tools/ForwardingFileObject.java b/src/java.compiler/share/classes/javax/tools/ForwardingFileObject.java
index ac776f3f290..57bdb84000e 100644
--- a/src/java.compiler/share/classes/javax/tools/ForwardingFileObject.java
+++ b/src/java.compiler/share/classes/javax/tools/ForwardingFileObject.java
@@ -38,6 +38,9 @@ import java.util.Objects;
  * might override some of these methods and might also provide
  * additional fields and methods.
  *
+ * <p>Unless stated otherwise, references in this class to "<em>this file object</em>"
+ * should be interpreted as referring indirectly to the {@link #fileObject delegate file object}.
+ *
  * @param <F> the kind of file object forwarded to by this object
  * @author Peter von der Ah&eacute;
  * @since 1.6
@@ -45,7 +48,7 @@ import java.util.Objects;
 public class ForwardingFileObject<F extends FileObject> implements FileObject {

     /**
-     * The file object which all methods are delegated to.
+     * The file object to which all methods are delegated.
      */
     protected final F fileObject;

diff --git a/src/java.compiler/share/classes/javax/tools/ForwardingJavaFileManager.java b/src/java.compiler/share/classes/javax/tools/ForwardingJavaFileManager.java
index 3d90c1e7ede..27b55f3603a 100644
--- a/src/java.compiler/share/classes/javax/tools/ForwardingJavaFileManager.java
+++ b/src/java.compiler/share/classes/javax/tools/ForwardingJavaFileManager.java
@@ -37,6 +37,9 @@ import javax.tools.JavaFileObject.Kind;
  * might override some of these methods and might also provide
  * additional fields and methods.
  *
+ * <p>Unless stated otherwise, references in this class to "<em>this file manager</em>"
+ * should be interpreted as referring indirectly to the {@link #fileManager delegate file manager}.
+ *
  * @param <M> the kind of file manager forwarded to by this object
  * @author Peter von der Ah&eacute;
  * @since 1.6
@@ -44,7 +47,7 @@ import javax.tools.JavaFileObject.Kind;
 public class ForwardingJavaFileManager<M extends JavaFileManager> implements JavaFileManager {

     /**
-     * The file manager which all methods are delegated to.
+     * The file manager to which all methods are delegated.
      */
     protected final M fileManager;

diff --git a/src/java.compiler/share/classes/javax/tools/ForwardingJavaFileObject.java b/src/java.compiler/share/classes/javax/tools/ForwardingJavaFileObject.java
index bf7ad8f70ad..90f607cf3dc 100644
--- a/src/java.compiler/share/classes/javax/tools/ForwardingJavaFileObject.java
+++ b/src/java.compiler/share/classes/javax/tools/ForwardingJavaFileObject.java
@@ -33,6 +33,9 @@ import javax.lang.model.element.NestingKind;
  * might override some of these methods and might also provide
  * additional fields and methods.
  *
+ * <p>Unless stated otherwise, references in this class to "<em>this file object</em>"
+ * should be interpreted as referring indirectly to the {@link #fileObject delegate file object}.
+ *
  * @param <F> the kind of file object forwarded to by this object
  * @author Peter von der Ah&eacute;
  * @since 1.6