Index: src/java/org/apache/lucene/search/IndexSearcher.java
===================================================================
--- src/java/org/apache/lucene/search/IndexSearcher.java	(revision 798959)
+++ src/java/org/apache/lucene/search/IndexSearcher.java	(working copy)
@@ -36,6 +36,14 @@
  * 
  * <p>Note that you can only access Hits from an IndexSearcher as long as it is
  * not yet closed, otherwise an IOException will be thrown. 
+ *
+ * <a name="thread-safety"></a><p><b>NOTE</b>: {@link
+ * <code>IndexSearcher</code>} instances are completely
+ * thread safe, meaning multiple threads can call any of its
+ * methods, concurrently.  If your application requires
+ * external synchronization, you should <b>not</b>
+ * synchronize on the <code>IndexSearcher</code> instance;
+ * use your own (non-Lucene) objects instead.</p>
  */
 public class IndexSearcher extends Searcher {
   IndexReader reader;
Index: src/java/org/apache/lucene/index/IndexReader.java
===================================================================
--- src/java/org/apache/lucene/index/IndexReader.java	(revision 798959)
+++ src/java/org/apache/lucene/index/IndexReader.java	(working copy)
@@ -67,6 +67,14 @@
  if you want to make changes with the resulting IndexReader.
  </p>
 
+ <a name="thread-safety"></a><p><b>NOTE</b>: {@link
+ <code>IndexReader</code>} instances are completely thread
+ safe, meaning multiple threads can call any of its methods,
+ concurrently.  If your application requires external
+ synchronization, you should <b>not</b> synchronize on the
+ <code>IndexReader</code> instance; use your own
+ (non-Lucene) objects instead.
+ 
  @version $Id$
 */
 public abstract class IndexReader implements Cloneable {
Index: src/java/org/apache/lucene/index/IndexWriter.java
===================================================================
--- src/java/org/apache/lucene/index/IndexWriter.java	(revision 798959)
+++ src/java/org/apache/lucene/index/IndexWriter.java	(working copy)
@@ -191,10 +191,10 @@
   <code>IndexWriter</code>} instances are completely thread
   safe, meaning multiple threads can call any of its
   methods, concurrently.  If your application requires
-  external synchronization, you should <b>not</b> use the
-  <code>IndexWriter</code> instance for synchronization as
-  this can lead to deadlock.  Use a private
-  <code>Object</code> instead. </p>
+  external synchronization, you should <b>not</b>
+  synchronize on the <code>IndexWriter</code> instance as
+  this may cause deadlock; use your own (non-Lucene) objects
+  instead. </p>
 */
 
 /*