Index: lucene/src/java/org/apache/lucene/index/IndexReader.java
===================================================================
--- lucene/src/java/org/apache/lucene/index/IndexReader.java	(revision 1023637)
+++ lucene/src/java/org/apache/lucene/index/IndexReader.java	(working copy)
@@ -842,6 +842,11 @@
   }
 
   /** Returns an unpositioned {@link TermDocs} enumerator.
+   * <p>
+   * Note: the TermDocs returned is unpositioned. Before using it, ensure
+   * that you first position it with {@link TermDocs#seek(Term)} or 
+   * {@link TermDocs#seek(TermEnum)}.
+   * 
    * @throws IOException if there is a low-level IO error
    */
   public abstract TermDocs termDocs() throws IOException;