Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8268820

Use apiNote in AutoCloseable.close javadoc

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P4
    • Resolution: Approved
    • Fix Version/s: 17
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Kind:
      behavioral
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      Changes inheritDoc behavior.
    • Interface Kind:
      Java API
    • Scope:
      SE

      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

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              darcy Joe Darcy
              Reporter:
              darcy Joe Darcy
              Reviewed By:
              Brian Burkhalter
              Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: