Index: lucene/src/test-framework/org/apache/lucene/analysis/MockAnalyzer.java =================================================================== --- lucene/src/test-framework/org/apache/lucene/analysis/MockAnalyzer.java (revision 1072155) +++ lucene/src/test-framework/org/apache/lucene/analysis/MockAnalyzer.java (working copy) @@ -36,6 +36,10 @@ private final boolean payload; private int positionIncrementGap; + /** + * Calls {@link #MockAnalyzer(CharacterRunAutomaton, boolean, CharacterRunAutomaton, boolean, boolean) + * MockAnalyzer(runAutomaton, lowerCase, filter, enablePositionIncrements, true}). + */ public MockAnalyzer(CharacterRunAutomaton runAutomaton, boolean lowerCase, CharacterRunAutomaton filter, boolean enablePositionIncrements) { this(runAutomaton, lowerCase, filter, enablePositionIncrements, true); } @@ -47,7 +51,7 @@ * @param lowerCase true if the tokenizer should lowercase terms * @param filter DFA describing how terms should be filtered (set of stopwords, etc) * @param enablePositionIncrements true if position increments should reflect filtered terms. - * @param payload if payloads should be added + * @param payload if payloads should be added containing the positions (for testing) */ public MockAnalyzer(CharacterRunAutomaton runAutomaton, boolean lowerCase, CharacterRunAutomaton filter, boolean enablePositionIncrements, boolean payload) { this.runAutomaton = runAutomaton; @@ -58,21 +62,26 @@ } /** - * Creates a new MockAnalyzer, with no filtering. - * - * @param runAutomaton DFA describing how tokenization should happen (e.g. [a-zA-Z]+) - * @param lowerCase true if the tokenizer should lowercase terms + * Calls {@link #MockAnalyzer(CharacterRunAutomaton, boolean, CharacterRunAutomaton, boolean, boolean) + * MockAnalyzer(runAutomaton, lowerCase, MockTokenFilter.EMPTY_STOPSET, false, true}). */ public MockAnalyzer(CharacterRunAutomaton runAutomaton, boolean lowerCase) { this(runAutomaton, lowerCase, MockTokenFilter.EMPTY_STOPSET, false, true); } + /** + * Calls {@link #MockAnalyzer(CharacterRunAutomaton, boolean, CharacterRunAutomaton, boolean, boolean) + * MockAnalyzer(runAutomaton, lowerCase, MockTokenFilter.EMPTY_STOPSET, false, payload}). + */ public MockAnalyzer(CharacterRunAutomaton runAutomaton, boolean lowerCase, boolean payload) { this(runAutomaton, lowerCase, MockTokenFilter.EMPTY_STOPSET, false, payload); } /** - * Create a Whitespace-lowercasing analyzer with no stopwords removal + * Create a Whitespace-lowercasing analyzer with no stopwords removal. + *

+ * Calls {@link #MockAnalyzer(CharacterRunAutomaton, boolean, CharacterRunAutomaton, boolean, boolean) + * MockAnalyzer(MockTokenizer.WHITESPACE, true, MockTokenFilter.EMPTY_STOPSET, false, true}). */ public MockAnalyzer() { this(MockTokenizer.WHITESPACE, true); Index: lucene/src/test-framework/org/apache/lucene/analysis/MockTokenFilter.java =================================================================== --- lucene/src/test-framework/org/apache/lucene/analysis/MockTokenFilter.java (revision 1072155) +++ lucene/src/test-framework/org/apache/lucene/analysis/MockTokenFilter.java (working copy) @@ -60,6 +60,13 @@ private final CharTermAttribute termAtt = addAttribute(CharTermAttribute.class); private final PositionIncrementAttribute posIncrAtt = addAttribute(PositionIncrementAttribute.class); + /** + * Create a new MockTokenFilter. + * + * @param input TokenStream to filter + * @param filter DFA representing the terms that should be removed. + * @param enablePositionIncrements true if the removal should accumulate position increments. + */ public MockTokenFilter(TokenStream input, CharacterRunAutomaton filter, boolean enablePositionIncrements) { super(input); this.filter = filter; Index: lucene/src/test-framework/org/apache/lucene/analysis/MockTokenizer.java =================================================================== --- lucene/src/test-framework/org/apache/lucene/analysis/MockTokenizer.java (revision 1072155) +++ lucene/src/test-framework/org/apache/lucene/analysis/MockTokenizer.java (working copy) @@ -20,7 +20,7 @@ import java.io.IOException; import java.io.Reader; -import org.apache.lucene.util.Version; +import org.apache.lucene.util.LuceneTestCase; import org.apache.lucene.util.automaton.CharacterRunAutomaton; import org.apache.lucene.util.automaton.RegExp; @@ -46,14 +46,14 @@ private int state; public MockTokenizer(AttributeFactory factory, Reader input, CharacterRunAutomaton runAutomaton, boolean lowerCase) { - super(Version.LUCENE_CURRENT, factory, input); + super(LuceneTestCase.TEST_VERSION_CURRENT, factory, input); this.runAutomaton = runAutomaton; this.lowerCase = lowerCase; this.state = runAutomaton.getInitialState(); } public MockTokenizer(Reader input, CharacterRunAutomaton runAutomaton, boolean lowerCase) { - super(Version.LUCENE_CURRENT, input); + super(LuceneTestCase.TEST_VERSION_CURRENT, input); this.runAutomaton = runAutomaton; this.lowerCase = lowerCase; this.state = runAutomaton.getInitialState(); Index: lucene/src/test-framework/org/apache/lucene/index/RandomIndexWriter.java =================================================================== --- lucene/src/test-framework/org/apache/lucene/index/RandomIndexWriter.java (revision 1072155) +++ lucene/src/test-framework/org/apache/lucene/index/RandomIndexWriter.java (working copy) @@ -91,6 +91,10 @@ } } + /** + * Adds a Document. + * @see IndexWriter#addDocument(Document) + */ public void addDocument(Document doc) throws IOException { w.addDocument(doc); if (docCount++ == flushAt) { @@ -102,6 +106,10 @@ } } + /** + * Updates a document. + * @see IndexWriter#updateDocument(Term, Document) + */ public void updateDocument(Term t, Document doc) throws IOException { w.updateDocument(t, doc); if (docCount++ == flushAt) { @@ -162,6 +170,10 @@ } } + /** + * Close this writer. + * @see IndexWriter#close() + */ public void close() throws IOException { // if someone isn't using getReader() API, we want to be sure to // maybeOptimize since presumably they might open a reader on the dir. @@ -171,6 +183,13 @@ w.close(); } + /** + * Forces an optimize. + *

+ * NOTE: this should be avoided in tests unless absolutely necessary, + * as it will result in less test coverage. + * @see IndexWriter#optimize() + */ public void optimize() throws IOException { w.optimize(); } Index: lucene/src/test-framework/org/apache/lucene/store/MockDirectoryWrapper.java =================================================================== --- lucene/src/test-framework/org/apache/lucene/store/MockDirectoryWrapper.java (revision 1072155) +++ lucene/src/test-framework/org/apache/lucene/store/MockDirectoryWrapper.java (working copy) @@ -38,6 +38,18 @@ /** * This is a Directory Wrapper that adds methods * intended to be used only by unit tests. + * It also adds a number of features useful for testing: + *

*/ public class MockDirectoryWrapper extends Directory { Index: lucene/src/test-framework/org/apache/lucene/util/LineFileDocs.java =================================================================== --- lucene/src/test-framework/org/apache/lucene/util/LineFileDocs.java (revision 1072155) +++ lucene/src/test-framework/org/apache/lucene/util/LineFileDocs.java (working copy) @@ -32,9 +32,9 @@ import org.apache.lucene.document.Document; import org.apache.lucene.document.Field; -// Minimal port of contrib/benchmark's LneDocSource + -// DocMaker, so tests can enum docs from a line file created -// by contrib/benchmark's WriteLineDoc task +/** Minimal port of contrib/benchmark's LneDocSource + + * DocMaker, so tests can enum docs from a line file created + * by contrib/benchmark's WriteLineDoc task */ public class LineFileDocs implements Closeable { private BufferedReader reader; @@ -42,8 +42,8 @@ private final AtomicInteger id = new AtomicInteger(); private final String path; - // If forever is true, we rewind the file at EOF (repeat - // the docs over and over) + /** If forever is true, we rewind the file at EOF (repeat + * the docs over and over) */ public LineFileDocs(Random random, String path) throws IOException { this.path = path; open(random); @@ -138,7 +138,7 @@ private final ThreadLocal threadDocs = new ThreadLocal(); - // Document instance is re-used per-thread + /** Note: Document instance is re-used per-thread */ public Document nextDoc() throws IOException { String line; synchronized(this) { Index: lucene/src/test-framework/org/apache/lucene/util/automaton/AutomatonTestUtil.java =================================================================== --- lucene/src/test-framework/org/apache/lucene/util/automaton/AutomatonTestUtil.java (revision 1072155) +++ lucene/src/test-framework/org/apache/lucene/util/automaton/AutomatonTestUtil.java (working copy) @@ -80,9 +80,9 @@ return new String(buffer, 0, end); } - // picks a random int code point, avoiding surrogates; - // throws IllegalArgumentException if this transition only - // accepts surrogates + /** picks a random int code point, avoiding surrogates; + * throws IllegalArgumentException if this transition only + * accepts surrogates */ private static int getRandomCodePoint(final Random r, final Transition t) { final int code; if (t.max < UnicodeUtil.UNI_SUR_HIGH_START || Index: lucene/src/test-framework/org/apache/lucene/util/LuceneTestCase.java =================================================================== --- lucene/src/test-framework/org/apache/lucene/util/LuceneTestCase.java (revision 1072155) +++ lucene/src/test-framework/org/apache/lucene/util/LuceneTestCase.java (working copy) @@ -708,7 +708,7 @@ } /** - * Convinience method for logging an iterator. + * Convenience method for logging an iterator. * * @param label String logged before/after the items in the iterator * @param iter Each next() is toString()ed and logged on it's own line. If iter is null this is logged differnetly then an empty iterator. @@ -728,7 +728,7 @@ } /** - * Convinience method for logging an array. Wraps the array in an iterator and delegates + * Convenience method for logging an array. Wraps the array in an iterator and delegates * * @see #dumpIterator(String,Iterator,PrintStream) */ @@ -743,6 +743,7 @@ return newIndexWriterConfig(random, v, a); } + /** create a new index writer config with random defaults using the specified random */ public static IndexWriterConfig newIndexWriterConfig(Random r, Version v, Analyzer a) { IndexWriterConfig c = new IndexWriterConfig(v, a); if (r.nextBoolean()) { @@ -835,6 +836,10 @@ return newDirectory(random); } + /** + * Returns a new Directory instance, using the specified random. + * See {@link #newDirectory()} for more information. + */ public static MockDirectoryWrapper newDirectory(Random r) throws IOException { Directory impl = newDirectoryImpl(r, TEST_DIRECTORY); MockDirectoryWrapper dir = new MockDirectoryWrapper(r, impl); @@ -889,6 +894,11 @@ } } + /** + * Returns a new Directory instance, using the specified random + * with contents copied from the provided directory. See + * {@link #newDirectory()} for more information. + */ public static MockDirectoryWrapper newDirectory(Random r, Directory d) throws IOException { Directory impl = newDirectoryImpl(r, TEST_DIRECTORY); for (String file : d.listAll()) { @@ -899,26 +909,45 @@ return dir; } + /** Returns a new field instance. + * See {@link #newField(String, String, Store, Index, TermVector)} for more information */ public static Field newField(String name, String value, Index index) { return newField(random, name, value, index); } + /** Returns a new field instance. + * See {@link #newField(String, String, Store, Index, TermVector)} for more information */ public static Field newField(String name, String value, Store store, Index index) { return newField(random, name, value, store, index); } + /** + * Returns a new Field instance. Use this when the test does not + * care about some specific field settings (most tests) + * + */ public static Field newField(String name, String value, Store store, Index index, TermVector tv) { return newField(random, name, value, store, index, tv); } + /** Returns a new field instance, using the specified random. + * See {@link #newField(String, String, Store, Index, TermVector)} for more information */ public static Field newField(Random random, String name, String value, Index index) { return newField(random, name, value, Store.NO, index); } + /** Returns a new field instance, using the specified random. + * See {@link #newField(String, String, Store, Index, TermVector)} for more information */ public static Field newField(Random random, String name, String value, Store store, Index index) { return newField(random, name, value, store, index, TermVector.NO); } + /** Returns a new field instance, using the specified random. + * See {@link #newField(String, String, Store, Index, TermVector)} for more information */ public static Field newField(Random random, String name, String value, Store store, Index index, TermVector tv) { if (!index.isIndexed()) return new Field(name, value, store, index); @@ -1029,7 +1058,8 @@ } } - /** create a new searcher over the reader */ + /** create a new searcher over the reader. + * This searcher might randomly use threads. */ public static IndexSearcher newSearcher(IndexReader r) throws IOException { if (random.nextBoolean()) { return new IndexSearcher(r); Index: lucene/src/test-framework/org/apache/lucene/util/_TestUtil.java =================================================================== --- lucene/src/test-framework/org/apache/lucene/util/_TestUtil.java (revision 1072155) +++ lucene/src/test-framework/org/apache/lucene/util/_TestUtil.java (working copy) @@ -52,6 +52,9 @@ return new File(LuceneTestCase.TEMP_DIR, desc + "." + new Random().nextLong()); } + /** + * Deletes a directory and everything underneath it. + */ public static void rmDir(File dir) throws IOException { if (dir.exists()) { for (File f : dir.listFiles()) { @@ -155,6 +158,9 @@ return randomUnicodeString(r, 20); } + /** + * Returns a random string up to a certain length. + */ public static String randomUnicodeString(Random r, int maxLength) { final int end = r.nextInt(maxLength); if (end == 0) { @@ -280,8 +286,8 @@ } } - // just tries to configure things to keep the open file - // count lowish + /** just tries to configure things to keep the open file + * count lowish */ public static void reduceOpenFiles(IndexWriter w) { // keep number of open files lowish LogMergePolicy lmp = (LogMergePolicy) w.getConfig().getMergePolicy();