JDK-8268820 : Use apiNote in AutoCloseable.close javadoc
  • Type: CSR
  • Component: core-libs
  • Sub-Component: java.lang
  • Priority: P4
  • Status: Closed
  • Resolution: Approved
  • Fix Versions: 17
  • Submitted: 2021-06-15
  • Updated: 2021-06-15
  • Resolved: 2021-06-15
Related Reports
CSR :  
Description
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


Comments
Moving to Approved.
15-06-2021