Index: lucene/core/src/java/org/apache/lucene/index/MultiFields.java
===================================================================
--- lucene/core/src/java/org/apache/lucene/index/MultiFields.java	(revision 1297475)
+++ lucene/core/src/java/org/apache/lucene/index/MultiFields.java	(working copy)
@@ -38,6 +38,9 @@
  * sub-readers (eg DirectoryReader or {@link
  * MultiReader}).
  *
+ * This API is internal; casual users should use 
+ * {@link org.apache.lucene.index.SlowCompositeReaderWrapper}.
+ *
  * <p><b>NOTE</b>: for multi readers, you'll get better
  * performance by gathering the sub readers using {@link
  * ReaderUtil#gatherSubReaders} and then operate per-reader,
Index: lucene/MIGRATE.txt
===================================================================
--- lucene/MIGRATE.txt	(revision 1297475)
+++ lucene/MIGRATE.txt	(working copy)
@@ -95,16 +95,23 @@
         }
 
       Do this:
- 
-        FieldsEnum fieldsEnum = ...;
-	String field;
-	while((field = fieldsEnum.next()) != null) {
-	  TermsEnum termsEnum = fieldsEnum.terms();
-	  BytesRef text;
-	  while((text = termsEnum.next()) != null) {
-	    System.out.println("field=" + field + "; text=" + text.utf8ToString());
-	  }
 
+        AtomicReader areader = SlowCompositeReaderWrapper.wrap(reader);
+        Fields fields = areader.fields();
+        if (fields != null) {
+          FieldsEnum fieldsEnum = fields.iterator(); 
+          String field;
+          while((field = fieldsEnum.next()) != null) {
+            Terms terms = fieldsEnum.terms();
+            if (terms != null) {
+            TermsEnum termsEnum = terms.iterator(null);
+            BytesRef text;
+            while((text = termsEnum.next()) != null) {
+              System.out.println("field=" + field + "; text=" + text.utf8ToString());
+            }
+          }
+       }
+
     * TermDocs is renamed to DocsEnum.  Instead of this:
 
         while(td.next()) {
@@ -200,27 +207,28 @@
   the Fields class.  If you know your reader is a single segment
   reader, do this:
 
-    Fields fields = reader.Fields();
+    Fields fields = reader.fields();
     if (fields != null) {
       ...
     }
 
   If the reader might be multi-segment, you must do this:
     
-    Fields fields = MultiFields.getFields(reader);
+    areader = SlowCompositeReaderWrapper.wrap(reader);
+    Fields fields = areader.fields();
     if (fields != null) {
       ...
     }
   
   The fields may be null (eg if the reader has no fields).
 
-  Note that the MultiFields approach entails a performance hit on
+  Note that the SlowCompositeReaderWrapper is, indeed, slow on
   MultiReaders, as it must merge terms/docs/positions on the fly. It's
   generally better to instead get the sequential readers (use
   oal.util.ReaderUtil) and then step through those readers yourself,
   if you can (this is how Lucene drives searches).
 
-  If you pass a SegmentReader to MultiFields.fiels it will simply
+  If you pass a SegmentReader to SlowCompositeReaderWrapper  it will simply
   return reader.fields(), so there is no performance hit in that
   case.