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,12 +38,15 @@
  * sub-readers (eg DirectoryReader or {@link
  * MultiReader}).
  *
+ * 
+ *
  * <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,
  * instead of using this class.
  *
- * @lucene.experimental
+ * @lucene.internal Casual users should use 
+ * {@link org.apache.lucene.index.SlowCompositeReaderWrapper}.
  */
 
 public final class MultiFields extends Fields {
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,28 +207,29 @@
   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
-  return reader.fields(), so there is no performance hit in that
+  If you pass a SegmentReader to SlowCompositeReaderWrapper.wrap it
+  will simply return itself, so there is no performance hit in that
   case.
 
   Once you have a non-null Fields you can do this: