7012279: Project Coin: Clarify AutoCloseable and Throwable javadoc

Reviewed-by: jjb

src/share/classes/java/lang/AutoCloseable.java

 /*
- * 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 @@ package java.lang;
  */
 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 @@ public interface AutoCloseable {
      * 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;

src/share/classes/java/lang/Throwable.java

 /*
- * 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 @@ public class Throwable implements Serializable {
     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 @@ public class Throwable implements Serializable {
     }
 
     /**
-     * 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