Index: src/java/org/apache/lucene/index/IndexWriter.java
===================================================================
--- src/java/org/apache/lucene/index/IndexWriter.java	(revision 798096)
+++ src/java/org/apache/lucene/index/IndexWriter.java	(working copy)
@@ -186,6 +186,15 @@
   last commit.  If you opened the writer with autoCommit
   false you can also just call {@link #rollback()}
   directly.</p>
+
+  <a name="thread-safety"></a><p><b>NOTE</b>: {@link
+  <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>
 */
 
 /*