diff --git a/lucene/contrib/misc/src/java/org/apache/lucene/index/BalancedSegmentMergePolicy.java b/lucene/contrib/misc/src/java/org/apache/lucene/index/BalancedSegmentMergePolicy.java index 2f9ebf7ac2e..3de5aebcd16 100644 --- a/lucene/contrib/misc/src/java/org/apache/lucene/index/BalancedSegmentMergePolicy.java +++ b/lucene/contrib/misc/src/java/org/apache/lucene/index/BalancedSegmentMergePolicy.java @@ -353,6 +353,9 @@ public class BalancedSegmentMergePolicy extends LogByteSizeMergePolicy { } + /** + * Specifies configuration parameters for BalancedSegmentMergePolicy. + */ public static class MergePolicyParams { private int _numLargeSegments; private int _maxSmallSegments; diff --git a/lucene/contrib/misc/src/java/org/apache/lucene/index/CompoundFileExtractor.java b/lucene/contrib/misc/src/java/org/apache/lucene/index/CompoundFileExtractor.java index 532b2d707b2..d8ef54a2d4a 100644 --- a/lucene/contrib/misc/src/java/org/apache/lucene/index/CompoundFileExtractor.java +++ b/lucene/contrib/misc/src/java/org/apache/lucene/index/CompoundFileExtractor.java @@ -37,6 +37,9 @@ import org.apache.lucene.store.IndexInput; import org.apache.lucene.util.ArrayUtil; import org.apache.lucene.util.CommandLineUtil; +/** + * Command-line tool for extracting sub-files out of a compound file. + */ public class CompoundFileExtractor { public static void main(String [] args) { @@ -63,7 +66,7 @@ public class CompoundFileExtractor { } if (filename == null) { - System.out.println("Usage: org.apache.lucene.index.IndexReader [-extract] [-dir-impl X] "); + System.out.println("Usage: org.apache.lucene.index.CompoundFileExtractor [-extract] [-dir-impl X] "); return; } diff --git a/lucene/contrib/misc/src/java/org/apache/lucene/misc/GetTermInfo.java b/lucene/contrib/misc/src/java/org/apache/lucene/misc/GetTermInfo.java index ae3faf966ce..45ab8d5ee6f 100644 --- a/lucene/contrib/misc/src/java/org/apache/lucene/misc/GetTermInfo.java +++ b/lucene/contrib/misc/src/java/org/apache/lucene/misc/GetTermInfo.java @@ -23,7 +23,7 @@ import org.apache.lucene.store.FSDirectory; import org.apache.lucene.util.BytesRef; import org.apache.lucene.index.IndexReader; -/* +/** * Utility to get document frequency and total number of occurrences (sum of the tf for each doc) of a term. */ public class GetTermInfo { diff --git a/lucene/core/src/java/org/apache/lucene/index/FieldInfo.java b/lucene/core/src/java/org/apache/lucene/index/FieldInfo.java index 34f9587008d..09a74763474 100644 --- a/lucene/core/src/java/org/apache/lucene/index/FieldInfo.java +++ b/lucene/core/src/java/org/apache/lucene/index/FieldInfo.java @@ -20,7 +20,13 @@ import org.apache.lucene.index.DocValues.Type; * limitations under the License. */ -/** @lucene.experimental */ +/** + * Access to the Fieldable Info file that describes document fields and whether or + * not they are indexed. Each segment has a separate Fieldable Info file. Objects + * of this class are thread-safe for multiple readers, but only one thread can + * be adding documents at a time, with no other reader or writer threads + * accessing this object. + **/ public final class FieldInfo { public final String name; public final int number; diff --git a/lucene/core/src/java/org/apache/lucene/index/FieldInfos.java b/lucene/core/src/java/org/apache/lucene/index/FieldInfos.java index e2af36f4f4e..3bfeea690a4 100644 --- a/lucene/core/src/java/org/apache/lucene/index/FieldInfos.java +++ b/lucene/core/src/java/org/apache/lucene/index/FieldInfos.java @@ -26,11 +26,8 @@ import java.util.TreeMap; import org.apache.lucene.index.FieldInfo.IndexOptions; -/** Access to the Field Info file that describes document fields and whether or - * not they are indexed. Each segment has a separate Field Info file. Objects - * of this class are thread-safe for multiple readers, but only one thread can - * be adding documents at a time, with no other reader or writer threads - * accessing this object. +/** + * Collection of {@link FieldInfo}s (accessible by number or by name). * @lucene.experimental */ public final class FieldInfos implements Iterable { diff --git a/lucene/core/src/java/org/apache/lucene/index/SegmentReader.java b/lucene/core/src/java/org/apache/lucene/index/SegmentReader.java index f2b8f88d579..03e3c31f413 100644 --- a/lucene/core/src/java/org/apache/lucene/index/SegmentReader.java +++ b/lucene/core/src/java/org/apache/lucene/index/SegmentReader.java @@ -28,6 +28,10 @@ import org.apache.lucene.store.IOContext; import org.apache.lucene.util.Bits; /** + * IndexReader implementation over a single segment. + *

+ * Instances pointing to the same segment (but with different deletes, etc) + * may share the same core data. * @lucene.experimental */ public final class SegmentReader extends AtomicReader { diff --git a/lucene/core/src/java/org/apache/lucene/index/SegmentWriteState.java b/lucene/core/src/java/org/apache/lucene/index/SegmentWriteState.java index db5a086569e..9a0eb85137e 100644 --- a/lucene/core/src/java/org/apache/lucene/index/SegmentWriteState.java +++ b/lucene/core/src/java/org/apache/lucene/index/SegmentWriteState.java @@ -24,6 +24,7 @@ import org.apache.lucene.util.InfoStream; import org.apache.lucene.util.MutableBits; /** + * Holder class for common parameters used during write. * @lucene.experimental */ public class SegmentWriteState { diff --git a/lucene/core/src/java/org/apache/lucene/index/TieredMergePolicy.java b/lucene/core/src/java/org/apache/lucene/index/TieredMergePolicy.java index 1724d56f5a0..b874299164c 100644 --- a/lucene/core/src/java/org/apache/lucene/index/TieredMergePolicy.java +++ b/lucene/core/src/java/org/apache/lucene/index/TieredMergePolicy.java @@ -35,7 +35,7 @@ import java.util.ArrayList; * separates how many segments are merged at once ({@link * #setMaxMergeAtOnce}) from how many segments are allowed * per tier ({@link #setSegmentsPerTier}). This merge - * policy also does not over-merge (ie, cascade merges). + * policy also does not over-merge (i.e. cascade merges). * *

For normal merging, this policy first computes a * "budget" of how many segments are allowed by be in the @@ -43,8 +43,8 @@ import java.util.ArrayList; * sorts segments by decreasing size (pro-rating by percent * deletes), and then finds the least-cost merge. Merge * cost is measured by a combination of the "skew" of the - * merge (size of largest seg divided by smallest seg), - * total merge size and pct deletes reclaimed, + * merge (size of largest segment divided by smallest segment), + * total merge size and percent deletes reclaimed, * so that merges with lower skew, smaller size * and those reclaiming more deletes, are * favored. diff --git a/lucene/core/src/java/org/apache/lucene/search/spans/SpanPositionCheckQuery.java b/lucene/core/src/java/org/apache/lucene/search/spans/SpanPositionCheckQuery.java index 6b12d739187..696b0d9966b 100644 --- a/lucene/core/src/java/org/apache/lucene/search/spans/SpanPositionCheckQuery.java +++ b/lucene/core/src/java/org/apache/lucene/search/spans/SpanPositionCheckQuery.java @@ -32,8 +32,7 @@ import java.util.Set; /** - * - * + * Base class for filtering a SpanQuery based on the position of a match. **/ public abstract class SpanPositionCheckQuery extends SpanQuery implements Cloneable { protected SpanQuery match; diff --git a/lucene/core/src/java/org/apache/lucene/store/ByteArrayDataInput.java b/lucene/core/src/java/org/apache/lucene/store/ByteArrayDataInput.java index 7a6f7f40442..90391494872 100644 --- a/lucene/core/src/java/org/apache/lucene/store/ByteArrayDataInput.java +++ b/lucene/core/src/java/org/apache/lucene/store/ByteArrayDataInput.java @@ -21,7 +21,12 @@ import java.io.IOException; import org.apache.lucene.util.BytesRef; -/** @lucene.experimental */ +/** + * DataInput backed by a byte array. + * WARNING: This class omits most low-level checks, + * so be sure to test heavily with assertions enabled. + * @lucene.experimental + */ public final class ByteArrayDataInput extends DataInput { private byte[] bytes; diff --git a/lucene/core/src/java/org/apache/lucene/store/ByteArrayDataOutput.java b/lucene/core/src/java/org/apache/lucene/store/ByteArrayDataOutput.java index ca613ef01be..863470bdf7d 100644 --- a/lucene/core/src/java/org/apache/lucene/store/ByteArrayDataOutput.java +++ b/lucene/core/src/java/org/apache/lucene/store/ByteArrayDataOutput.java @@ -20,6 +20,9 @@ package org.apache.lucene.store; import org.apache.lucene.util.BytesRef; /** + * DataOutput backed by a byte array. + * WARNING: This class omits most low-level checks, + * so be sure to test heavily with assertions enabled. * @lucene.experimental */ public class ByteArrayDataOutput extends DataOutput { diff --git a/lucene/core/src/java/org/apache/lucene/util/Bits.java b/lucene/core/src/java/org/apache/lucene/util/Bits.java index dd74818ff67..84ea3347825 100644 --- a/lucene/core/src/java/org/apache/lucene/util/Bits.java +++ b/lucene/core/src/java/org/apache/lucene/util/Bits.java @@ -18,6 +18,7 @@ package org.apache.lucene.util; */ /** + * Interface for Bitset-like structures. * @lucene.experimental */ @@ -27,6 +28,9 @@ public interface Bits { public static final Bits[] EMPTY_ARRAY = new Bits[0]; + /** + * Bits impl of the specified length with all bits set. + */ public static class MatchAllBits implements Bits { final int len; @@ -43,6 +47,9 @@ public interface Bits { } } + /** + * Bits impl of the specified length with no bits set. + */ public static class MatchNoBits implements Bits { final int len; diff --git a/lucene/core/src/java/org/apache/lucene/util/CodecUtil.java b/lucene/core/src/java/org/apache/lucene/util/CodecUtil.java index 2f2605de37d..fc38faee3a0 100644 --- a/lucene/core/src/java/org/apache/lucene/util/CodecUtil.java +++ b/lucene/core/src/java/org/apache/lucene/util/CodecUtil.java @@ -27,6 +27,9 @@ import org.apache.lucene.store.DataInput; import org.apache.lucene.store.DataOutput; /** + * Utility class for reading and writing versioned headers. + * This is useful to ensure that a file is in the format + * you think it is. * @lucene.experimental */ diff --git a/lucene/test-framework/src/java/org/apache/lucene/analysis/BaseTokenStreamTestCase.java b/lucene/test-framework/src/java/org/apache/lucene/analysis/BaseTokenStreamTestCase.java index 5e140f17566..aaaffa7597a 100644 --- a/lucene/test-framework/src/java/org/apache/lucene/analysis/BaseTokenStreamTestCase.java +++ b/lucene/test-framework/src/java/org/apache/lucene/analysis/BaseTokenStreamTestCase.java @@ -49,10 +49,18 @@ import org.apache.lucene.util._TestUtil; public abstract class BaseTokenStreamTestCase extends LuceneTestCase { // some helpers to test Analyzers and TokenStreams: + /** + * Attribute that records if it was cleared or not. This is used + * for testing that clearAttributes() was called correctly. + */ public static interface CheckClearAttributesAttribute extends Attribute { boolean getAndResetClearCalled(); } + /** + * Attribute that records if it was cleared or not. This is used + * for testing that clearAttributes() was called correctly. + */ public static final class CheckClearAttributesAttributeImpl extends AttributeImpl implements CheckClearAttributesAttribute { private boolean clearCalled = false; diff --git a/lucene/test-framework/src/java/org/apache/lucene/analysis/CannedTokenStream.java b/lucene/test-framework/src/java/org/apache/lucene/analysis/CannedTokenStream.java index 4703c2369d3..d4f39e99f47 100644 --- a/lucene/test-framework/src/java/org/apache/lucene/analysis/CannedTokenStream.java +++ b/lucene/test-framework/src/java/org/apache/lucene/analysis/CannedTokenStream.java @@ -25,7 +25,7 @@ import org.apache.lucene.analysis.tokenattributes.PayloadAttribute; import org.apache.lucene.analysis.tokenattributes.PositionIncrementAttribute; /** - * emits a canned set of {@link Token} + * TokenStream from a canned list of Tokens. */ public final class CannedTokenStream extends TokenStream { private final Token[] tokens; diff --git a/lucene/test-framework/src/java/org/apache/lucene/analysis/CollationTestBase.java b/lucene/test-framework/src/java/org/apache/lucene/analysis/CollationTestBase.java index feb205ae87f..23e17525799 100644 --- a/lucene/test-framework/src/java/org/apache/lucene/analysis/CollationTestBase.java +++ b/lucene/test-framework/src/java/org/apache/lucene/analysis/CollationTestBase.java @@ -48,6 +48,9 @@ import java.io.IOException; import java.util.HashMap; import java.util.Map; +/** + * Base test class for testing Unicode collation. + */ public abstract class CollationTestBase extends LuceneTestCase { protected String firstRangeBeginningOriginal = "\u062F"; diff --git a/lucene/test-framework/src/java/org/apache/lucene/analysis/MockFixedLengthPayloadFilter.java b/lucene/test-framework/src/java/org/apache/lucene/analysis/MockFixedLengthPayloadFilter.java index af0c3646257..74e233924ee 100644 --- a/lucene/test-framework/src/java/org/apache/lucene/analysis/MockFixedLengthPayloadFilter.java +++ b/lucene/test-framework/src/java/org/apache/lucene/analysis/MockFixedLengthPayloadFilter.java @@ -23,6 +23,9 @@ import java.util.Random; import org.apache.lucene.analysis.tokenattributes.PayloadAttribute; import org.apache.lucene.index.Payload; +/** + * TokenFilter that adds random fixed-length payloads. + */ public final class MockFixedLengthPayloadFilter extends TokenFilter { private final PayloadAttribute payloadAtt = addAttribute(PayloadAttribute.class); private final Random random; diff --git a/lucene/test-framework/src/java/org/apache/lucene/analysis/MockVariableLengthPayloadFilter.java b/lucene/test-framework/src/java/org/apache/lucene/analysis/MockVariableLengthPayloadFilter.java index f7b5361df83..0397deee50a 100644 --- a/lucene/test-framework/src/java/org/apache/lucene/analysis/MockVariableLengthPayloadFilter.java +++ b/lucene/test-framework/src/java/org/apache/lucene/analysis/MockVariableLengthPayloadFilter.java @@ -23,6 +23,9 @@ import java.util.Random; import org.apache.lucene.analysis.tokenattributes.PayloadAttribute; import org.apache.lucene.index.Payload; +/** + * TokenFilter that adds random variable-length payloads. + */ public final class MockVariableLengthPayloadFilter extends TokenFilter { private static final int MAXLENGTH = 129; diff --git a/lucene/test-framework/src/java/org/apache/lucene/index/MockIndexInput.java b/lucene/test-framework/src/java/org/apache/lucene/index/MockIndexInput.java index f1006f6a8d0..87fa6bcba67 100644 --- a/lucene/test-framework/src/java/org/apache/lucene/index/MockIndexInput.java +++ b/lucene/test-framework/src/java/org/apache/lucene/index/MockIndexInput.java @@ -19,6 +19,11 @@ package org.apache.lucene.index; import org.apache.lucene.store.BufferedIndexInput; +// TODO: what is this used for? just testing BufferedIndexInput? +// if so it should be pkg-private. otherwise its a dup of ByteArrayIndexInput? +/** + * IndexInput backed by a byte[] for testing. + */ public class MockIndexInput extends BufferedIndexInput { private byte[] buffer; private int pointer = 0; diff --git a/lucene/test-framework/src/java/org/apache/lucene/index/MockRandomMergePolicy.java b/lucene/test-framework/src/java/org/apache/lucene/index/MockRandomMergePolicy.java index c44902fb261..74dc06c3256 100644 --- a/lucene/test-framework/src/java/org/apache/lucene/index/MockRandomMergePolicy.java +++ b/lucene/test-framework/src/java/org/apache/lucene/index/MockRandomMergePolicy.java @@ -26,6 +26,9 @@ import java.util.Map; import org.apache.lucene.util._TestUtil; +/** + * MergePolicy that makes random decisions for testing. + */ public class MockRandomMergePolicy extends MergePolicy { private final Random random; diff --git a/lucene/test-framework/src/java/org/apache/lucene/search/CheckHits.java b/lucene/test-framework/src/java/org/apache/lucene/search/CheckHits.java index 5705e1dd870..adab4d734e2 100644 --- a/lucene/test-framework/src/java/org/apache/lucene/search/CheckHits.java +++ b/lucene/test-framework/src/java/org/apache/lucene/search/CheckHits.java @@ -30,6 +30,9 @@ import org.apache.lucene.index.IndexReader; import org.apache.lucene.store.Directory; import org.apache.lucene.util.LuceneTestCase; +/** + * Utility class for asserting expected hits in tests. + */ public class CheckHits { /** @@ -118,6 +121,9 @@ public class CheckHits { } } + /** + * Just collects document ids into a set. + */ public static class SetCollector extends Collector { final Set bag; public SetCollector(Set bag) { diff --git a/lucene/test-framework/src/java/org/apache/lucene/search/QueryUtils.java b/lucene/test-framework/src/java/org/apache/lucene/search/QueryUtils.java index aba98f89188..bac9b8c718b 100644 --- a/lucene/test-framework/src/java/org/apache/lucene/search/QueryUtils.java +++ b/lucene/test-framework/src/java/org/apache/lucene/search/QueryUtils.java @@ -41,9 +41,9 @@ import org.apache.lucene.util._TestUtil; import static org.apache.lucene.util.LuceneTestCase.TEST_VERSION_CURRENT; - - - +/** + * Utility class for sanity-checking queries. + */ public class QueryUtils { /** Check the types of things query objects should be able to do. */ diff --git a/lucene/test-framework/src/java/org/apache/lucene/store/MockLockFactoryWrapper.java b/lucene/test-framework/src/java/org/apache/lucene/store/MockLockFactoryWrapper.java index b51889ffa8c..e056a1f07cd 100644 --- a/lucene/test-framework/src/java/org/apache/lucene/store/MockLockFactoryWrapper.java +++ b/lucene/test-framework/src/java/org/apache/lucene/store/MockLockFactoryWrapper.java @@ -19,6 +19,10 @@ package org.apache.lucene.store; import java.io.IOException; +/** + * Used by MockDirectoryWrapper to wrap another factory + * and track open locks. + */ public class MockLockFactoryWrapper extends LockFactory { MockDirectoryWrapper dir; LockFactory delegate; diff --git a/lucene/test-framework/src/java/org/apache/lucene/util/ThrottledIndexOutput.java b/lucene/test-framework/src/java/org/apache/lucene/util/ThrottledIndexOutput.java index fcded42166f..5564a3193c6 100644 --- a/lucene/test-framework/src/java/org/apache/lucene/util/ThrottledIndexOutput.java +++ b/lucene/test-framework/src/java/org/apache/lucene/util/ThrottledIndexOutput.java @@ -21,6 +21,9 @@ import java.io.IOException; import org.apache.lucene.store.DataInput; import org.apache.lucene.store.IndexOutput; +/** + * Intentionally slow IndexOutput for testing. + */ public class ThrottledIndexOutput extends IndexOutput { public static final int DEFAULT_MIN_WRITTEN_BYTES = 1024; private final int bytesPerSecond; diff --git a/lucene/test-framework/src/java/org/apache/lucene/util/_TestUtil.java b/lucene/test-framework/src/java/org/apache/lucene/util/_TestUtil.java index bac8464365e..d8dce5574b2 100644 --- a/lucene/test-framework/src/java/org/apache/lucene/util/_TestUtil.java +++ b/lucene/test-framework/src/java/org/apache/lucene/util/_TestUtil.java @@ -63,6 +63,9 @@ import org.apache.lucene.search.TopDocs; import org.apache.lucene.store.Directory; import org.junit.Assert; +/** + * General utility methods for Lucene unit tests. + */ public class _TestUtil { /** Returns temp dir, based on String arg in its name; diff --git a/modules/analysis/common/src/java/org/apache/lucene/analysis/hunspell/HunspellDictionary.java b/modules/analysis/common/src/java/org/apache/lucene/analysis/hunspell/HunspellDictionary.java index 6b5818558b8..e66389bd274 100644 --- a/modules/analysis/common/src/java/org/apache/lucene/analysis/hunspell/HunspellDictionary.java +++ b/modules/analysis/common/src/java/org/apache/lucene/analysis/hunspell/HunspellDictionary.java @@ -29,6 +29,10 @@ import java.util.Arrays; import java.util.List; import java.util.Locale; +/** + * In-memory structure for the dictionary (.dic) and affix (.aff) + * data of a hunspell dictionary. + */ public class HunspellDictionary { static final HunspellWord NOFLAGS = new HunspellWord(); diff --git a/modules/analysis/common/src/java/org/apache/lucene/analysis/hunspell/HunspellWord.java b/modules/analysis/common/src/java/org/apache/lucene/analysis/hunspell/HunspellWord.java index fbb4ae93e12..8a0c2063042 100644 --- a/modules/analysis/common/src/java/org/apache/lucene/analysis/hunspell/HunspellWord.java +++ b/modules/analysis/common/src/java/org/apache/lucene/analysis/hunspell/HunspellWord.java @@ -19,6 +19,9 @@ package org.apache.lucene.analysis.hunspell; import java.util.Arrays; +/** + * A dictionary (.dic) entry with its associated flags. + */ public class HunspellWord { private final char flags[]; // sorted, can we represent more concisely? diff --git a/modules/analysis/common/src/java/org/apache/lucene/analysis/path/PathHierarchyTokenizer.java b/modules/analysis/common/src/java/org/apache/lucene/analysis/path/PathHierarchyTokenizer.java index 608c386625d..26b5b1d3a28 100644 --- a/modules/analysis/common/src/java/org/apache/lucene/analysis/path/PathHierarchyTokenizer.java +++ b/modules/analysis/common/src/java/org/apache/lucene/analysis/path/PathHierarchyTokenizer.java @@ -25,7 +25,8 @@ import org.apache.lucene.analysis.tokenattributes.OffsetAttribute; import org.apache.lucene.analysis.tokenattributes.PositionIncrementAttribute; /** - * + * Tokenizer for path-like hierarchies. + *

* Take something like: * * 

diff --git a/modules/analysis/common/src/java/org/apache/lucene/analysis/path/ReversePathHierarchyTokenizer.java b/modules/analysis/common/src/java/org/apache/lucene/analysis/path/ReversePathHierarchyTokenizer.java
index 07aa11fbbaf..fc8a6831742 100644
--- a/modules/analysis/common/src/java/org/apache/lucene/analysis/path/ReversePathHierarchyTokenizer.java
+++ b/modules/analysis/common/src/java/org/apache/lucene/analysis/path/ReversePathHierarchyTokenizer.java
@@ -27,7 +27,8 @@ import org.apache.lucene.analysis.tokenattributes.OffsetAttribute;
 import org.apache.lucene.analysis.tokenattributes.PositionIncrementAttribute;
 
 /**
- *
+ * Tokenizer for domain-like hierarchies.
+ * 

  * Take something like:
  *
  * 
diff --git a/modules/analysis/common/src/java/org/apache/lucene/analysis/sinks/TeeSinkTokenFilter.java b/modules/analysis/common/src/java/org/apache/lucene/analysis/sinks/TeeSinkTokenFilter.java
index ade1b216295..c5aff60497f 100644
--- a/modules/analysis/common/src/java/org/apache/lucene/analysis/sinks/TeeSinkTokenFilter.java
+++ b/modules/analysis/common/src/java/org/apache/lucene/analysis/sinks/TeeSinkTokenFilter.java
@@ -182,6 +182,9 @@ public final class TeeSinkTokenFilter extends TokenFilter {
     }
   }
   
+  /**
+   * TokenStream output from a tee with optional filtering.
+   */
   public static final class SinkTokenStream extends TokenStream {
     private final List cachedStates = new LinkedList();
     private AttributeSource.State finalState;
diff --git a/modules/analysis/common/src/java/org/apache/lucene/analysis/sinks/TokenTypeSinkFilter.java b/modules/analysis/common/src/java/org/apache/lucene/analysis/sinks/TokenTypeSinkFilter.java
index e8706c621c4..b5488a8ad60 100644
--- a/modules/analysis/common/src/java/org/apache/lucene/analysis/sinks/TokenTypeSinkFilter.java
+++ b/modules/analysis/common/src/java/org/apache/lucene/analysis/sinks/TokenTypeSinkFilter.java
@@ -20,6 +20,9 @@ package org.apache.lucene.analysis.sinks;
 import org.apache.lucene.analysis.tokenattributes.TypeAttribute;
 import org.apache.lucene.util.AttributeSource;
 
+/**
+ * Adds a token to the sink if it has a specific type.
+ */
 public class TokenTypeSinkFilter extends TeeSinkTokenFilter.SinkFilter {
   private String typeToMatch;
   private TypeAttribute typeAtt;
diff --git a/modules/analysis/common/src/java/org/apache/lucene/analysis/standard/StandardTokenizerInterface.java b/modules/analysis/common/src/java/org/apache/lucene/analysis/standard/StandardTokenizerInterface.java
index eb2f0d7d161..a3a17c31f27 100644
--- a/modules/analysis/common/src/java/org/apache/lucene/analysis/standard/StandardTokenizerInterface.java
+++ b/modules/analysis/common/src/java/org/apache/lucene/analysis/standard/StandardTokenizerInterface.java
@@ -22,7 +22,10 @@ import org.apache.lucene.analysis.tokenattributes.CharTermAttribute;
 import java.io.Reader;
 import java.io.IOException;
 
-/** @lucene.internal */
+/** 
+ * Internal interface for supporting versioned grammars.
+ * @lucene.internal 
+ */
 public interface StandardTokenizerInterface {
 
   /** This character denotes the end of file */
diff --git a/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/GraphvizFormatter.java b/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/GraphvizFormatter.java
index d7186bdfc0b..51e3f11e2e2 100644
--- a/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/GraphvizFormatter.java
+++ b/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/GraphvizFormatter.java
@@ -31,6 +31,9 @@ import org.apache.lucene.analysis.kuromoji.dict.Dictionary;
 // TODO: would be nice to show 2nd best path in a diff't
 // color...
 
+/**
+ * Outputs the dot (graphviz) string for the viterbi lattice.
+ */
 public class GraphvizFormatter {
   
   private final static String BOS_LABEL = "BOS";
diff --git a/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/KuromojiAnalyzer.java b/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/KuromojiAnalyzer.java
index cc6020f21ba..1689e410c96 100644
--- a/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/KuromojiAnalyzer.java
+++ b/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/KuromojiAnalyzer.java
@@ -33,6 +33,9 @@ import org.apache.lucene.analysis.util.CharArraySet;
 import org.apache.lucene.analysis.util.StopwordAnalyzerBase;
 import org.apache.lucene.util.Version;
 
+/**
+ * Analyzer for Japanese that uses morphological analysis.
+ */
 public class KuromojiAnalyzer extends StopwordAnalyzerBase {
   private final Mode mode;
   private final Set stoptags;
diff --git a/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/KuromojiTokenizer.java b/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/KuromojiTokenizer.java
index 90f032bdfad..e340708f1aa 100644
--- a/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/KuromojiTokenizer.java
+++ b/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/KuromojiTokenizer.java
@@ -55,6 +55,9 @@ import org.apache.lucene.util.fst.FST;
  * penalties to the long tokens.  If so, and the Mode is
  * SEARCH_WITH_COMPOUND, we output the alternate
  * segmentation as well. */
+/**
+ * Tokenizer for Japanese that uses morphological analysis.
+ */
 public final class KuromojiTokenizer extends Tokenizer {
 
   public static enum Mode {
diff --git a/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/Token.java b/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/Token.java
index 02c9adb0a87..6a1aef7abaa 100644
--- a/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/Token.java
+++ b/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/Token.java
@@ -20,6 +20,9 @@ package org.apache.lucene.analysis.kuromoji;
 import org.apache.lucene.analysis.kuromoji.KuromojiTokenizer.Type;
 import org.apache.lucene.analysis.kuromoji.dict.Dictionary;
 
+/**
+ * Analyzed token with morphological data from its dictionary.
+ */
 public class Token {
   private final Dictionary dictionary;
   
diff --git a/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/dict/BinaryDictionary.java b/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/dict/BinaryDictionary.java
index c11acfa95e5..7f383c30170 100644
--- a/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/dict/BinaryDictionary.java
+++ b/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/dict/BinaryDictionary.java
@@ -32,6 +32,9 @@ import org.apache.lucene.util.CodecUtil;
 import org.apache.lucene.util.IntsRef;
 import org.apache.lucene.util.IOUtils;
 
+/**
+ * Base class for a binary-encoded in-memory dictionary.
+ */
 public abstract class BinaryDictionary implements Dictionary {
   
   public static final String DICT_FILENAME_SUFFIX = "$buffer.dat";
diff --git a/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/dict/CharacterDefinition.java b/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/dict/CharacterDefinition.java
index f548a9dd5e0..123d640fb0d 100644
--- a/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/dict/CharacterDefinition.java
+++ b/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/dict/CharacterDefinition.java
@@ -26,6 +26,9 @@ import org.apache.lucene.store.InputStreamDataInput;
 import org.apache.lucene.util.CodecUtil;
 import org.apache.lucene.util.IOUtils;
 
+/**
+ * Character category data.
+ */
 public final class CharacterDefinition {
 
   public static final String FILENAME_SUFFIX = ".dat";
diff --git a/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/dict/ConnectionCosts.java b/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/dict/ConnectionCosts.java
index 55f56914c14..f26b927e1df 100644
--- a/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/dict/ConnectionCosts.java
+++ b/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/dict/ConnectionCosts.java
@@ -26,6 +26,9 @@ import org.apache.lucene.store.InputStreamDataInput;
 import org.apache.lucene.util.CodecUtil;
 import org.apache.lucene.util.IOUtils;
 
+/**
+ * n-gram connection cost data
+ */
 public final class ConnectionCosts {
   
   public static final String FILENAME_SUFFIX = ".dat";
diff --git a/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/dict/Dictionary.java b/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/dict/Dictionary.java
index 6fc89511f95..7f21cb49595 100644
--- a/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/dict/Dictionary.java
+++ b/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/dict/Dictionary.java
@@ -17,6 +17,10 @@ package org.apache.lucene.analysis.kuromoji.dict;
  * limitations under the License.
  */
 
+/**
+ * Dictionary interface for retrieving morphological data
+ * by id.
+ */
 public interface Dictionary {
   
   public static final String INTERNAL_SEPARATOR = "\u0000";
diff --git a/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/dict/TokenInfoDictionary.java b/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/dict/TokenInfoDictionary.java
index 68075072ed7..3fddf25c3a1 100644
--- a/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/dict/TokenInfoDictionary.java
+++ b/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/dict/TokenInfoDictionary.java
@@ -26,6 +26,10 @@ import org.apache.lucene.util.IOUtils;
 import org.apache.lucene.util.fst.FST;
 import org.apache.lucene.util.fst.PositiveIntOutputs;
 
+/**
+ * Binary dictionary implementation for a known-word dictionary model:
+ * Words are encoded into an FST mapping to a list of wordIDs.
+ */
 public final class TokenInfoDictionary extends BinaryDictionary {
 
   public static final String FST_FILENAME_SUFFIX = "$fst.dat";
diff --git a/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/dict/TokenInfoFST.java b/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/dict/TokenInfoFST.java
index 553724199ff..46def27c110 100644
--- a/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/dict/TokenInfoFST.java
+++ b/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/dict/TokenInfoFST.java
@@ -22,6 +22,13 @@ import java.io.IOException;
 import org.apache.lucene.util.fst.FST;
 import org.apache.lucene.util.fst.FST.Arc;
 
+/**
+ * Thin wrapper around an FST with root-arc caching for Japanese.
+ * 

+ * Depending upon fasterButMoreRam, either just kana (191 arcs),
+ * or kana and han (28,607 arcs) are cached. The latter offers
+ * additional performance at the cost of more RAM.
+ */
 public final class TokenInfoFST {
   private final FST fst;
 
diff --git a/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/dict/UnknownDictionary.java b/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/dict/UnknownDictionary.java
index eb219cba040..8f800b0d05c 100644
--- a/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/dict/UnknownDictionary.java
+++ b/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/dict/UnknownDictionary.java
@@ -19,6 +19,9 @@ package org.apache.lucene.analysis.kuromoji.dict;
 
 import java.io.IOException;
 
+/**
+ * Dictionary for unknown-word handling.
+ */
 public final class UnknownDictionary extends BinaryDictionary {
 
   private final CharacterDefinition characterDefinition = CharacterDefinition.getInstance();
diff --git a/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/dict/UserDictionary.java b/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/dict/UserDictionary.java
index 5d43ce9a8c5..7190d76cf3a 100644
--- a/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/dict/UserDictionary.java
+++ b/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/dict/UserDictionary.java
@@ -34,6 +34,10 @@ import org.apache.lucene.util.fst.Builder;
 import org.apache.lucene.util.fst.FST;
 import org.apache.lucene.util.fst.PositiveIntOutputs;
 
+/**
+ * Class for building a User Dictionary.
+ * This class allows for custom segmentation of phrases.
+ */
 public final class UserDictionary implements Dictionary {
   
   // phrase text -> phrase ID
diff --git a/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/tokenattributes/BaseFormAttributeImpl.java b/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/tokenattributes/BaseFormAttributeImpl.java
index e090f7ab1ba..5f4ffdc9ef2 100644
--- a/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/tokenattributes/BaseFormAttributeImpl.java
+++ b/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/tokenattributes/BaseFormAttributeImpl.java
@@ -21,6 +21,9 @@ import org.apache.lucene.analysis.kuromoji.Token;
 import org.apache.lucene.util.AttributeImpl;
 import org.apache.lucene.util.AttributeReflector;
 
+/**
+ * Attribute for {@link Token#getBaseForm()}.
+ */
 public class BaseFormAttributeImpl extends AttributeImpl implements BaseFormAttribute, Cloneable {
   private Token token;
   
diff --git a/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/tokenattributes/InflectionAttributeImpl.java b/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/tokenattributes/InflectionAttributeImpl.java
index 9c9bd9675d7..c1af59c6838 100644
--- a/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/tokenattributes/InflectionAttributeImpl.java
+++ b/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/tokenattributes/InflectionAttributeImpl.java
@@ -22,6 +22,9 @@ import org.apache.lucene.analysis.kuromoji.util.ToStringUtil;
 import org.apache.lucene.util.AttributeImpl;
 import org.apache.lucene.util.AttributeReflector;
 
+/**
+ * Attribute for Kuromoji inflection data.
+ */
 public class InflectionAttributeImpl extends AttributeImpl implements InflectionAttribute, Cloneable {
   private Token token;
   
diff --git a/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/tokenattributes/PartOfSpeechAttributeImpl.java b/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/tokenattributes/PartOfSpeechAttributeImpl.java
index e83578fe834..257b17f559e 100644
--- a/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/tokenattributes/PartOfSpeechAttributeImpl.java
+++ b/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/tokenattributes/PartOfSpeechAttributeImpl.java
@@ -22,6 +22,9 @@ import org.apache.lucene.analysis.kuromoji.util.ToStringUtil;
 import org.apache.lucene.util.AttributeImpl;
 import org.apache.lucene.util.AttributeReflector;
 
+/**
+ * Attribute for {@link Token#getPartOfSpeech()}.
+ */
 public class PartOfSpeechAttributeImpl extends AttributeImpl implements PartOfSpeechAttribute, Cloneable {
   private Token token;
   
diff --git a/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/tokenattributes/ReadingAttributeImpl.java b/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/tokenattributes/ReadingAttributeImpl.java
index 8bc998a267e..41d10b9623d 100644
--- a/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/tokenattributes/ReadingAttributeImpl.java
+++ b/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/tokenattributes/ReadingAttributeImpl.java
@@ -22,6 +22,9 @@ import org.apache.lucene.analysis.kuromoji.util.ToStringUtil;
 import org.apache.lucene.util.AttributeImpl;
 import org.apache.lucene.util.AttributeReflector;
 
+/**
+ * Attribute for Kuromoji reading data
+ */
 public class ReadingAttributeImpl extends AttributeImpl implements ReadingAttribute, Cloneable {
   private Token token;
   
diff --git a/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/util/CSVUtil.java b/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/util/CSVUtil.java
index 1bb1faf7385..1a873527bde 100644
--- a/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/util/CSVUtil.java
+++ b/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/util/CSVUtil.java
@@ -21,6 +21,9 @@ import java.util.ArrayList;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
+/**
+ * Utility class for parsing CSV text
+ */
 public final class CSVUtil {
   private static final char QUOTE = '"';
   
diff --git a/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/util/ToStringUtil.java b/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/util/ToStringUtil.java
index 7d2e792cb99..fb19233e8a9 100644
--- a/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/util/ToStringUtil.java
+++ b/modules/analysis/kuromoji/src/java/org/apache/lucene/analysis/kuromoji/util/ToStringUtil.java
@@ -19,6 +19,10 @@ package org.apache.lucene.analysis.kuromoji.util;
 
 import java.util.HashMap;
 
+/**
+ * Utility class for english translations of morphological data,
+ * used only for debugging.
+ */
 public class ToStringUtil {
   // a translation map for parts of speech, only used for reflectWith
   private static final HashMap posTranslations = new HashMap();
diff --git a/modules/analysis/phonetic/src/java/org/apache/lucene/analysis/phonetic/DoubleMetaphoneFilter.java b/modules/analysis/phonetic/src/java/org/apache/lucene/analysis/phonetic/DoubleMetaphoneFilter.java
index 971c9b4f7a5..ff6af52e33b 100644
--- a/modules/analysis/phonetic/src/java/org/apache/lucene/analysis/phonetic/DoubleMetaphoneFilter.java
+++ b/modules/analysis/phonetic/src/java/org/apache/lucene/analysis/phonetic/DoubleMetaphoneFilter.java
@@ -25,6 +25,9 @@ import org.apache.lucene.analysis.TokenStream;
 import org.apache.lucene.analysis.tokenattributes.CharTermAttribute;
 import org.apache.lucene.analysis.tokenattributes.PositionIncrementAttribute;
 
+/**
+ * Filter for DoubleMetaphone (supporting secondary codes)
+ */
 public final class DoubleMetaphoneFilter extends TokenFilter {
 
   private static final String TOKEN_TYPE = "DoubleMetaphone";
diff --git a/modules/benchmark/src/java/org/apache/lucene/benchmark/Constants.java b/modules/benchmark/src/java/org/apache/lucene/benchmark/Constants.java
index 42926321c8f..9d920efd4ad 100644
--- a/modules/benchmark/src/java/org/apache/lucene/benchmark/Constants.java
+++ b/modules/benchmark/src/java/org/apache/lucene/benchmark/Constants.java
@@ -18,8 +18,7 @@ package org.apache.lucene.benchmark;
 
 
 /**
- *
- *
+ * Various benchmarking constants (mostly defaults)
  **/
 public class Constants
 {
diff --git a/modules/benchmark/src/java/org/apache/lucene/benchmark/byTask/feeds/DirContentSource.java b/modules/benchmark/src/java/org/apache/lucene/benchmark/byTask/feeds/DirContentSource.java
index 66dcac8e41e..82292e28131 100644
--- a/modules/benchmark/src/java/org/apache/lucene/benchmark/byTask/feeds/DirContentSource.java
+++ b/modules/benchmark/src/java/org/apache/lucene/benchmark/byTask/feeds/DirContentSource.java
@@ -49,6 +49,9 @@ public class DirContentSource extends ContentSource {
     ParsePosition pos;
   }
   
+  /**
+   * Iterator over the files in the directory
+   */
   public static class Iterator implements java.util.Iterator {
 
     static class Comparator implements java.util.Comparator {
diff --git a/modules/benchmark/src/java/org/apache/lucene/benchmark/byTask/feeds/LongToEnglishQueryMaker.java b/modules/benchmark/src/java/org/apache/lucene/benchmark/byTask/feeds/LongToEnglishQueryMaker.java
index 7b414491540..982092d6273 100644
--- a/modules/benchmark/src/java/org/apache/lucene/benchmark/byTask/feeds/LongToEnglishQueryMaker.java
+++ b/modules/benchmark/src/java/org/apache/lucene/benchmark/byTask/feeds/LongToEnglishQueryMaker.java
@@ -29,9 +29,9 @@ import org.apache.lucene.util.Version;
 import com.ibm.icu.text.RuleBasedNumberFormat;
 
 /**
- *
- *
- **/
+ * Creates queries whose content is a spelled-out long number 
+ * starting from {@link Long#MIN_VALUE} + 10.
+ */
 public class LongToEnglishQueryMaker implements QueryMaker {
   long counter = Long.MIN_VALUE + 10;
   protected QueryParser parser;
diff --git a/modules/benchmark/src/java/org/apache/lucene/benchmark/byTask/tasks/PrintReaderTask.java b/modules/benchmark/src/java/org/apache/lucene/benchmark/byTask/tasks/PrintReaderTask.java
index 25b1e46a6c1..db6422e8097 100644
--- a/modules/benchmark/src/java/org/apache/lucene/benchmark/byTask/tasks/PrintReaderTask.java
+++ b/modules/benchmark/src/java/org/apache/lucene/benchmark/byTask/tasks/PrintReaderTask.java
@@ -21,6 +21,9 @@ import org.apache.lucene.benchmark.byTask.PerfRunData;
 import org.apache.lucene.index.IndexReader;
 import org.apache.lucene.store.Directory;
 
+/**
+ * Opens a reader and prints basic statistics.
+ */
 public class PrintReaderTask extends PerfTask {
   private String userData = null;
   
diff --git a/modules/benchmark/src/java/org/apache/lucene/benchmark/quality/trec/QueryDriver.java b/modules/benchmark/src/java/org/apache/lucene/benchmark/quality/trec/QueryDriver.java
index aacdf26be40..afdd0141aad 100644
--- a/modules/benchmark/src/java/org/apache/lucene/benchmark/quality/trec/QueryDriver.java
+++ b/modules/benchmark/src/java/org/apache/lucene/benchmark/quality/trec/QueryDriver.java
@@ -33,8 +33,7 @@ import java.util.Set;
 
 
 /**
- *
- *
+ * Command-line tool for doing a TREC evaluation run.
  **/
 public class QueryDriver {
   public static void main(String[] args) throws Exception {
diff --git a/modules/suggest/src/java/org/apache/lucene/search/spell/JaroWinklerDistance.java b/modules/suggest/src/java/org/apache/lucene/search/spell/JaroWinklerDistance.java
index 38181732470..9bcde795acf 100644
--- a/modules/suggest/src/java/org/apache/lucene/search/spell/JaroWinklerDistance.java
+++ b/modules/suggest/src/java/org/apache/lucene/search/spell/JaroWinklerDistance.java
@@ -19,6 +19,11 @@ package org.apache.lucene.search.spell;
 
 import java.util.Arrays;
 
+/**
+ * Similarity measure for short strings such as person names.
+ * 

+ * @see http://en.wikipedia.org/wiki/Jaro%E2%80%93Winkler_distance
+ */
 public class JaroWinklerDistance implements StringDistance {
 
   private float threshold = 0.7f;
diff --git a/modules/suggest/src/java/org/apache/lucene/search/spell/TermFreqIterator.java b/modules/suggest/src/java/org/apache/lucene/search/spell/TermFreqIterator.java
index 64df7687e73..ebc19c0ec9f 100644
--- a/modules/suggest/src/java/org/apache/lucene/search/spell/TermFreqIterator.java
+++ b/modules/suggest/src/java/org/apache/lucene/search/spell/TermFreqIterator.java
@@ -23,10 +23,17 @@ import java.util.Comparator;
 import org.apache.lucene.util.BytesRef;
 import org.apache.lucene.util.BytesRefIterator;
 
+/**
+ * Interface for enumerating term,weight pairs.
+ */
 public interface TermFreqIterator extends BytesRefIterator {
 
   public long weight();
   
+  /**
+   * Wraps a BytesRefIterator as a TermFreqIterator, with all weights
+   * set to 1
+   */
   public static class TermFreqIteratorWrapper implements TermFreqIterator {
     private BytesRefIterator wrapped;