# HG changeset patch
# User darcy
# Date 1294986118 28800
# Node ID d31b7cc371efe780d3af772d4a0b63dc4766427c
# Parent  04c9822b55c9c2a31660fdb9d9ba484bd7c131a1
7012279: Project Coin: Clarify AutoCloseable and Throwable javadoc
Reviewed-by: jjb

diff -r 04c9822b55c9 -r d31b7cc371ef jdk/src/share/classes/java/lang/AutoCloseable.java
--- a/jdk/src/share/classes/java/lang/AutoCloseable.java	Thu Jan 13 20:32:12 2011 -0800
+++ b/jdk/src/share/classes/java/lang/AutoCloseable.java	Thu Jan 13 22:21:58 2011 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009, 2010, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2009, 2011, 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
@@ -33,7 +33,7 @@
  */
 public interface AutoCloseable {
     /**
-     * Close this resource, relinquishing any underlying resources.
+     * Closes this resource, relinquishing any underlying resources.
      * This method is invoked automatically by the {@code
      * try}-with-resources statement.
      *
@@ -48,6 +48,10 @@
      * visible side effect, unlike {@code Closeable.close} which is
      * required to have no effect if called more than once.
      *
+     * However, while not required to be idempotent, implementers of
+     * this interface are strongly encouraged to make their {@code
+     * close} methods idempotent.
+     *
      * @throws Exception if this resource cannot be closed
      */
     void close() throws Exception;
diff -r 04c9822b55c9 -r d31b7cc371ef jdk/src/share/classes/java/lang/Throwable.java
--- a/jdk/src/share/classes/java/lang/Throwable.java	Thu Jan 13 20:32:12 2011 -0800
+++ b/jdk/src/share/classes/java/lang/Throwable.java	Thu Jan 13 22:21:58 2011 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1994, 2010, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1994, 2011, 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
@@ -809,7 +809,7 @@
     native StackTraceElement getStackTraceElement(int index);
 
     /**
-     * Read a {@code Throwable} from a stream, enforcing
+     * Reads a {@code Throwable} from a stream, enforcing
      * well-formedness constraints on fields.  Null entries and
      * self-pointers are not allowed in the list of {@code
      * suppressedExceptions}.  Null entries are not allowed for stack
@@ -865,9 +865,10 @@
     }
 
     /**
-     * Adds the specified exception to the list of exceptions that
-     * were suppressed, typically by the {@code try}-with-resources
-     * statement, in order to deliver this exception.
+     * Appends the specified exception to the exceptions that were
+     * suppressed in order to deliver this exception. This method is
+     * typically called (automatically and implicitly) by the {@code
+     * try}-with-resources statement.
      *
      * If the first exception to be suppressed is {@code null}, that
      * indicates suppressed exception information will <em>not</em> be