Summary

Make general guidance in AutoCloseable.close an apiNote.

Problem

The general guidance given in AutoCloseable.close is not ideal if inherited by inheritDoc to implementions and thus should be listed in a javadoc tag that is not inherited.

Solution

Put the text in question into an apiNote.

Specification

-- a/src/java.base/share/classes/java/lang/AutoCloseable.java
+++ b/src/java.base/share/classes/java/lang/AutoCloseable.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2009, 2021, 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
@@ -54,7 +54,8 @@ public interface AutoCloseable {
      * This method is invoked automatically on objects managed by the
      * {@code try}-with-resources statement.
      *
-     * <p>While this interface method is declared to throw {@code
+     * @apiNote
+     * While this interface method is declared to throw {@code
      * Exception}, implementers are <em>strongly</em> encouraged to
      * declare concrete implementations of the {@code close} method to
      * throw more specific exceptions, or to throw no exception at all