> On Dec 3, 2015, at 2:33 PM, Kim Barrett <kim.barr...@oracle.com> wrote:
>
> I prefer the explicit list in the opening sentence, rather than
> collapsing that to just "References", to avoid any possible confusion
> that this might apply to (the internal and undocumented, but visible
> in the code) FinalReference.
The explicit list was what I tried to avoid as it’s repeated in the other
sentences. FinalReference is not part of java.lang.ref spec and I don’t think
it could cause any confusion.
>
> I included a serial comma in the list; I generally prefer that usage,
> and it's consistent with earlier usage on the same page.
>
> In the final sentence, I prefer to avoid the use of "must", especially
> without any "to be useful" qualification, as that sounds like it might
> be a formal requirement, and that would be inconsistent with the
> PhantomReference constructor documentation.
>
> The second sentence (about soft and weak references) could be deleted,
> along with the "by contrast" phrase in the third, without loss of
> information. It does save the reader a bit of inference though.
>
> [Indeed, this whole section isn't strictly necessary; all of it can be
> inferred from information in other places.]
Agree. This section is no longer necessary and maybe just remove it:
--- a/src/java.base/share/classes/java/lang/ref/package-info.java
+++ b/src/java.base/share/classes/java/lang/ref/package-info.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1998, 2003, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2015, 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
@@ -43,8 +43,7 @@
* implementing memory-sensitive caches, weak references are for
* implementing canonicalizing mappings that do not prevent their keys
* (or values) from being reclaimed, and phantom references are for
- * scheduling pre-mortem cleanup actions in a more flexible way than
- * is possible with the Java finalization mechanism.
+ * scheduling post-mortem cleanup actions.
*
* <p> Each reference-object type is implemented by a subclass of the
* abstract base {@link java.lang.ref.Reference} class.
@@ -64,9 +63,9 @@
* object with a <em>reference queue</em> at the time the reference
* object is created. Some time after the garbage collector
* determines that the reachability of the referent has changed to the
- * value corresponding to the type of the reference, it will add the
- * reference to the associated queue. At this point, the reference is
- * considered to be <em>enqueued</em>. The program may remove
+ * value corresponding to the type of the reference, it will clear the
+ * reference and add it to the associated queue. At this point, the
+ * reference is considered to be <em>enqueued</em>. The program may remove
* references from a queue either by polling or by blocking until a
* reference becomes available. Reference queues are implemented by
* the {@link java.lang.ref.ReferenceQueue} class.
@@ -92,16 +91,6 @@
* structure, this check will add little overhead to the hashtable
* access methods.
*
- * <h3>Automatically-cleared references</h3>
- *
- * Soft and weak references are automatically cleared by the collector
- * before being added to the queues with which they are registered, if
- * any. Therefore soft and weak references need not be registered
- * with a queue in order to be useful, while phantom references do.
- * An object that is reachable via phantom references will remain so
- * until all such references are cleared or themselves become
- * unreachable.
- *
* <a name="reachability"></a>
* <h3>Reachability</h3>
*
Mandy
