diff --git a/CHANGES.txt b/CHANGES.txt
index ad8a47c3fe9..b15f5d22a3c 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -18,6 +18,10 @@ API Changes
  2. LUCENE-944: Remove deprecated methods setUseScorer14() and
     getUseScorer14() from BooleanQuery. (Paul Elschot via Michael Busch)
  
+ 5. LUCENE-963: Add setters to Field to allow for re-using a single
+    Field instance during indexing.  This is a sizable performance
+    gain, especially for small documents.  (Mike McCandless)
+
 Bug fixes
 
  1. LUCENE-933: QueryParser fixed to not produce empty sub 
diff --git a/src/java/org/apache/lucene/document/Field.java b/src/java/org/apache/lucene/document/Field.java
index 16d932633ab..5e49d1acbe6 100644
--- a/src/java/org/apache/lucene/document/Field.java
+++ b/src/java/org/apache/lucene/document/Field.java
@@ -156,30 +156,35 @@ public final class Field extends AbstractField implements Fieldable, Serializabl
   public TokenStream tokenStreamValue()   { return fieldsData instanceof TokenStream ? (TokenStream)fieldsData : null; }
   
 
-  /** Expert: change the value of this field.  This can be
-   *  used during indexing to re-use a single Field instance
-   *  to improve indexing speed. */
+  /** <p>Expert: change the value of this field.  This can
+   *  be used during indexing to re-use a single Field
+   *  instance to improve indexing speed by avoiding GC cost
+   *  of new'ing and reclaiming Field instances.  Typically
+   *  a single {@link Document} instance is re-used as
+   *  well.  This helps most on small documents.</p>
+   * 
+   *  <p>Note that you should only use this method after the
+   *  Field has been consumed (ie, the {@link Document}
+   *  containing this Field has been added to the index).
+   *  Also, each Field instance should only be used once
+   *  within a single {@link Document} instance.  See <a
+   *  href="http://wiki.apache.org/lucene-java/ImproveIndexingSpeed">ImproveIndexingSpeed</a>
+   *  for details.</p> */
   public void setValue(String value) {
     fieldsData = value;
   }
 
-  /** Expert: change the value of this field.  This can be
-   *  used during indexing to re-use a single Field instance
-   *  to improve indexing speed. */
+  /** Expert: change the value of this field.  See <a href="#setValue(java.lang.String)">setValue(String)</a>. */
   public void setValue(Reader value) {
     fieldsData = value;
   }
 
-  /** Expert: change the value of this field.  This can be
-   *  used during indexing to re-use a single Field instance
-   *  to improve indexing speed. */
+  /** Expert: change the value of this field.  See <a href="#setValue(java.lang.String)">setValue(String)</a>. */
   public void setValue(byte[] value) {
     fieldsData = value;
   }
 
-  /** Expert: change the value of this field.  This can be
-   *  used during indexing to re-use a single Field instance
-   *  to improve indexing speed. */
+  /** Expert: change the value of this field.  See <a href="#setValue(java.lang.String)">setValue(String)</a>. */
   public void setValue(TokenStream value) {
     fieldsData = value;
   }