From c58ad92c53c243da7d424d6d77d24ac1be0d5cc7 Mon Sep 17 00:00:00 2001 From: Robert Muir Date: Mon, 30 Apr 2012 17:11:22 +0000 Subject: [PATCH] LUCENE-3902: minor javadocs cleanups/nitpicks/formatting and visibility issues git-svn-id: https://svn.apache.org/repos/asf/lucene/dev/trunk@1332297 13f79535-47bb-0310-9956-ffa450edef68 --- .../lucene/codecs/BlockTreeTermsWriter.java | 9 +++---- .../intblock/VariableIntBlockIndexInput.java | 2 +- .../org/apache/lucene/document/Field.java | 4 +-- .../org/apache/lucene/document/FieldType.java | 3 +++ .../org/apache/lucene/index/CheckIndex.java | 6 +++-- .../lucene/index/IndexWriterConfig.java | 26 +++++++++++++------ .../lucene/index/IndexableFieldType.java | 5 +++- .../apache/lucene/index/MultiTermsEnum.java | 2 +- .../lucene/index/NormsConsumerPerField.java | 2 +- .../apache/lucene/index/SegmentReadState.java | 1 + .../lucene/index/StoredFieldVisitor.java | 16 +++++++++--- .../lucene/search/payloads/package.html | 11 +++----- .../search/similarities/MultiSimilarity.java | 6 ++--- .../search/spans/SpanPositionCheckQuery.java | 19 +++++++++++--- .../util/automaton/ByteRunAutomaton.java | 3 +++ .../util/automaton/CharacterRunAutomaton.java | 3 +++ .../lucene/util/automaton/UTF32ToUTF8.java | 5 +++- .../java/org/apache/lucene/util/fst/Util.java | 2 +- 18 files changed, 84 insertions(+), 41 deletions(-) diff --git a/lucene/core/src/java/org/apache/lucene/codecs/BlockTreeTermsWriter.java b/lucene/core/src/java/org/apache/lucene/codecs/BlockTreeTermsWriter.java index 232753d9079..6433b56b3ac 100644 --- a/lucene/core/src/java/org/apache/lucene/codecs/BlockTreeTermsWriter.java +++ b/lucene/core/src/java/org/apache/lucene/codecs/BlockTreeTermsWriter.java @@ -69,20 +69,19 @@ import org.apache.lucene.util.fst.Util; suffix, and 2) bulk-encode this array using bulk int[] codecs; then at search time we can binary search when we seek a particular term. +*/ /** + * block-based terms index and dictionary writer. + *

* Writes terms dict and index, block-encoding (column * stride) each term's metadata for each set of terms * between two index terms. * + * @see BlockTreeTermsReader * @lucene.experimental */ -/** See {@link BlockTreeTermsReader}. - * - * @lucene.experimental -*/ - public class BlockTreeTermsWriter extends FieldsConsumer { public final static int DEFAULT_MIN_BLOCK_SIZE = 25; diff --git a/lucene/core/src/java/org/apache/lucene/codecs/intblock/VariableIntBlockIndexInput.java b/lucene/core/src/java/org/apache/lucene/codecs/intblock/VariableIntBlockIndexInput.java index de972a88384..c8a0b12bc41 100644 --- a/lucene/core/src/java/org/apache/lucene/codecs/intblock/VariableIntBlockIndexInput.java +++ b/lucene/core/src/java/org/apache/lucene/codecs/intblock/VariableIntBlockIndexInput.java @@ -73,7 +73,7 @@ public abstract class VariableIntBlockIndexInput extends IntIndexInput { public void seek(long pos) throws IOException; } - public static class Reader extends IntIndexInput.Reader { + private static class Reader extends IntIndexInput.Reader { private final IndexInput in; public final int[] pending; diff --git a/lucene/core/src/java/org/apache/lucene/document/Field.java b/lucene/core/src/java/org/apache/lucene/document/Field.java index 492e224d7f2..6e5840eae5d 100644 --- a/lucene/core/src/java/org/apache/lucene/document/Field.java +++ b/lucene/core/src/java/org/apache/lucene/document/Field.java @@ -35,14 +35,14 @@ import org.apache.lucene.util.BytesRef; import org.apache.lucene.index.FieldInvertState; // javadocs /** - * Expert: directly creata a field for a document. Most + * Expert: directly create a field for a document. Most * users should use one of the sugar subclasses: {@link * IntField}, {@link LongField}, {@link FloatField}, {@link * DoubleField}, {@link DocValuesField}, {@link * StringField}, {@link TextField}, {@link StoredField}. * *

A field is a section of a Document. Each field has three - * parts: name, type andvalue. Values may be text + * parts: name, type and value. Values may be text * (String, Reader or pre-analyzed TokenStream), binary * (byte[]), or numeric (a Number). Fields are optionally stored in the * index, so that they may be returned with hits on the document. diff --git a/lucene/core/src/java/org/apache/lucene/document/FieldType.java b/lucene/core/src/java/org/apache/lucene/document/FieldType.java index 28e7c7595f6..dd9b6acb02c 100644 --- a/lucene/core/src/java/org/apache/lucene/document/FieldType.java +++ b/lucene/core/src/java/org/apache/lucene/document/FieldType.java @@ -23,6 +23,9 @@ import org.apache.lucene.index.IndexableFieldType; import org.apache.lucene.search.NumericRangeQuery; // javadocs import org.apache.lucene.util.NumericUtils; +/** + * Describes the properties of a field. + */ public class FieldType implements IndexableFieldType { /** Data type of the numeric value diff --git a/lucene/core/src/java/org/apache/lucene/index/CheckIndex.java b/lucene/core/src/java/org/apache/lucene/index/CheckIndex.java index 610f39a24a7..6d5d69bd8bc 100644 --- a/lucene/core/src/java/org/apache/lucene/index/CheckIndex.java +++ b/lucene/core/src/java/org/apache/lucene/index/CheckIndex.java @@ -134,8 +134,7 @@ public class CheckIndex { /** Holds the status of each segment in the index. * See {@link #segmentInfos}. * - *

WARNING: this API is new and experimental and is - * subject to suddenly change in the next release. + * @lucene.experimental */ public static class SegmentInfoStatus { /** Name of the segment. */ @@ -272,6 +271,9 @@ public class CheckIndex { public Throwable error = null; } + /** + * Status from testing DocValues + */ public static final class DocValuesStatus { /** Number of documents tested. */ public int docCount; diff --git a/lucene/core/src/java/org/apache/lucene/index/IndexWriterConfig.java b/lucene/core/src/java/org/apache/lucene/index/IndexWriterConfig.java index d2c9cdad5cd..ca1f1d0b0c2 100644 --- a/lucene/core/src/java/org/apache/lucene/index/IndexWriterConfig.java +++ b/lucene/core/src/java/org/apache/lucene/index/IndexWriterConfig.java @@ -51,15 +51,25 @@ import org.apache.lucene.util.Version; public final class IndexWriterConfig implements Cloneable { /** - * Specifies the open mode for {@link IndexWriter}: - *

+ * Specifies the open mode for {@link IndexWriter}. */ - public static enum OpenMode { CREATE, APPEND, CREATE_OR_APPEND } + public static enum OpenMode { + /** + * Creates a new index or overwrites an existing one. + */ + CREATE, + + /** + * Opens an existing index. + */ + APPEND, + + /** + * Creates a new index if one does not exist, + * otherwise it opens the index and documents will be appended. + */ + CREATE_OR_APPEND + } /** Default value is 32. Change using {@link #setTermIndexInterval(int)}. */ public static final int DEFAULT_TERM_INDEX_INTERVAL = 32; // TODO: this should be private to the codec, not settable here diff --git a/lucene/core/src/java/org/apache/lucene/index/IndexableFieldType.java b/lucene/core/src/java/org/apache/lucene/index/IndexableFieldType.java index 620503689ad..38b974954a6 100644 --- a/lucene/core/src/java/org/apache/lucene/index/IndexableFieldType.java +++ b/lucene/core/src/java/org/apache/lucene/index/IndexableFieldType.java @@ -19,7 +19,10 @@ package org.apache.lucene.index; import org.apache.lucene.index.FieldInfo.IndexOptions; -/** @lucene.experimental */ +/** + * Describes the properties of a field. + * @lucene.experimental + */ public interface IndexableFieldType { /** True if this field should be indexed (inverted) */ diff --git a/lucene/core/src/java/org/apache/lucene/index/MultiTermsEnum.java b/lucene/core/src/java/org/apache/lucene/index/MultiTermsEnum.java index c22228144de..a84785d8222 100644 --- a/lucene/core/src/java/org/apache/lucene/index/MultiTermsEnum.java +++ b/lucene/core/src/java/org/apache/lucene/index/MultiTermsEnum.java @@ -52,7 +52,7 @@ public final class MultiTermsEnum extends TermsEnum { private BytesRef current; private Comparator termComp; - public static class TermsEnumIndex { + static class TermsEnumIndex { public final static TermsEnumIndex[] EMPTY_ARRAY = new TermsEnumIndex[0]; final int subIndex; final TermsEnum termsEnum; diff --git a/lucene/core/src/java/org/apache/lucene/index/NormsConsumerPerField.java b/lucene/core/src/java/org/apache/lucene/index/NormsConsumerPerField.java index 5096734dedf..366820e5f71 100644 --- a/lucene/core/src/java/org/apache/lucene/index/NormsConsumerPerField.java +++ b/lucene/core/src/java/org/apache/lucene/index/NormsConsumerPerField.java @@ -21,7 +21,7 @@ import org.apache.lucene.codecs.DocValuesConsumer; import org.apache.lucene.index.DocValues.Type; import org.apache.lucene.search.similarities.Similarity; -public class NormsConsumerPerField extends InvertedDocEndConsumerPerField implements Comparable { +final class NormsConsumerPerField extends InvertedDocEndConsumerPerField implements Comparable { private final FieldInfo fieldInfo; private final DocumentsWriterPerThread.DocState docState; private final Similarity similarity; diff --git a/lucene/core/src/java/org/apache/lucene/index/SegmentReadState.java b/lucene/core/src/java/org/apache/lucene/index/SegmentReadState.java index b59d572a9d4..0583b509576 100644 --- a/lucene/core/src/java/org/apache/lucene/index/SegmentReadState.java +++ b/lucene/core/src/java/org/apache/lucene/index/SegmentReadState.java @@ -21,6 +21,7 @@ import org.apache.lucene.store.Directory; import org.apache.lucene.store.IOContext; /** + * Holder class for common parameters used during read. * @lucene.experimental */ public class SegmentReadState { diff --git a/lucene/core/src/java/org/apache/lucene/index/StoredFieldVisitor.java b/lucene/core/src/java/org/apache/lucene/index/StoredFieldVisitor.java index 99a1fde6e29..95fee32da0c 100644 --- a/lucene/core/src/java/org/apache/lucene/index/StoredFieldVisitor.java +++ b/lucene/core/src/java/org/apache/lucene/index/StoredFieldVisitor.java @@ -59,14 +59,24 @@ public abstract class StoredFieldVisitor { public void doubleField(FieldInfo fieldInfo, double value) throws IOException { } + /** + * Hook before processing a field. + * Before a field is processed, this method is invoked so that + * subclasses can return a {@link Status} representing whether + * they need that particular field or not, or to stop processing + * entirely. + */ public abstract Status needsField(FieldInfo fieldInfo) throws IOException; + /** + * Enumeration of possible return values for {@link #needsField}. + */ public static enum Status { - /** yes, i want the field */ + /** YES: the field should be visited. */ YES, - /** no, i do not */ + /** NO: don't visit this field, but continue processing fields for this document. */ NO, - /** stop loading fields for this document entirely */ + /** STOP: don't visit this field and stop processing any other fields for this document. */ STOP } } \ No newline at end of file diff --git a/lucene/core/src/java/org/apache/lucene/search/payloads/package.html b/lucene/core/src/java/org/apache/lucene/search/payloads/package.html index 9658169f06a..a193f89399d 100644 --- a/lucene/core/src/java/org/apache/lucene/search/payloads/package.html +++ b/lucene/core/src/java/org/apache/lucene/search/payloads/package.html @@ -19,19 +19,14 @@ org.apache.lucene.search.payloads -
The payloads package provides Query mechanisms for finding and using payloads. - +The payloads package provides Query mechanisms for finding and using payloads. +

The following Query implementations are provided: -

-
  1. {@link org.apache.lucene.search.payloads.PayloadTermQuery PayloadTermQuery} -- Boost a term's score based on the value of the payload located at that term.
  2. {@link org.apache.lucene.search.payloads.PayloadNearQuery PayloadNearQuery} -- A {@link org.apache.lucene.search.spans.SpanNearQuery SpanNearQuery} that factors in the value of the payloads located at each of the positions where the spans occur.
-
-
 
-
-
+

diff --git a/lucene/core/src/java/org/apache/lucene/search/similarities/MultiSimilarity.java b/lucene/core/src/java/org/apache/lucene/search/similarities/MultiSimilarity.java index 25a0448aadf..b15e87cfa2a 100644 --- a/lucene/core/src/java/org/apache/lucene/search/similarities/MultiSimilarity.java +++ b/lucene/core/src/java/org/apache/lucene/search/similarities/MultiSimilarity.java @@ -72,7 +72,7 @@ public class MultiSimilarity extends Similarity { return new MultiSloppyDocScorer(subScorers); } - public static class MultiExactDocScorer extends ExactSimScorer { + static class MultiExactDocScorer extends ExactSimScorer { private final ExactSimScorer subScorers[]; MultiExactDocScorer(ExactSimScorer subScorers[]) { @@ -98,7 +98,7 @@ public class MultiSimilarity extends Similarity { } } - public static class MultiSloppyDocScorer extends SloppySimScorer { + static class MultiSloppyDocScorer extends SloppySimScorer { private final SloppySimScorer subScorers[]; MultiSloppyDocScorer(SloppySimScorer subScorers[]) { @@ -134,7 +134,7 @@ public class MultiSimilarity extends Similarity { } } - public static class MultiStats extends SimWeight { + static class MultiStats extends SimWeight { final SimWeight subStats[]; MultiStats(SimWeight subStats[]) { 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 696b0d9966b..d3a1b690c4c 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 @@ -60,11 +60,22 @@ public abstract class SpanPositionCheckQuery extends SpanQuery implements Clonea match.extractTerms(terms); } - /** Return value if the match should be accepted {@code YES}, rejected {@code NO}, - * or rejected and enumeration should advance to the next document {@code NO_AND_ADVANCE}. - * @see #acceptPosition(Spans) + /** + * Return value for {@link SpanPositionCheckQuery#acceptPosition(Spans)}. */ - protected static enum AcceptStatus { YES, NO, NO_AND_ADVANCE }; + protected static enum AcceptStatus { + /** Indicates the match should be accepted */ + YES, + + /** Indicates the match should be rejected */ + NO, + + /** + * Indicates the match should be rejected, and the enumeration should advance + * to the next document. + */ + NO_AND_ADVANCE + }; /** * Implementing classes are required to return whether the current position is a match for the passed in diff --git a/lucene/core/src/java/org/apache/lucene/util/automaton/ByteRunAutomaton.java b/lucene/core/src/java/org/apache/lucene/util/automaton/ByteRunAutomaton.java index ae8d20396cf..e8191a70476 100644 --- a/lucene/core/src/java/org/apache/lucene/util/automaton/ByteRunAutomaton.java +++ b/lucene/core/src/java/org/apache/lucene/util/automaton/ByteRunAutomaton.java @@ -17,6 +17,9 @@ package org.apache.lucene.util.automaton; * limitations under the License. */ +/** + * Automaton representation for matching UTF-8 byte[]. + */ public class ByteRunAutomaton extends RunAutomaton { public ByteRunAutomaton(Automaton a) { diff --git a/lucene/core/src/java/org/apache/lucene/util/automaton/CharacterRunAutomaton.java b/lucene/core/src/java/org/apache/lucene/util/automaton/CharacterRunAutomaton.java index 76508c14590..d7675e45cd9 100644 --- a/lucene/core/src/java/org/apache/lucene/util/automaton/CharacterRunAutomaton.java +++ b/lucene/core/src/java/org/apache/lucene/util/automaton/CharacterRunAutomaton.java @@ -17,6 +17,9 @@ package org.apache.lucene.util.automaton; * limitations under the License. */ +/** + * Automaton representation for matching char[]. + */ public class CharacterRunAutomaton extends RunAutomaton { public CharacterRunAutomaton(Automaton a) { diff --git a/lucene/core/src/java/org/apache/lucene/util/automaton/UTF32ToUTF8.java b/lucene/core/src/java/org/apache/lucene/util/automaton/UTF32ToUTF8.java index fbe42db5826..ce98e2cb2d6 100644 --- a/lucene/core/src/java/org/apache/lucene/util/automaton/UTF32ToUTF8.java +++ b/lucene/core/src/java/org/apache/lucene/util/automaton/UTF32ToUTF8.java @@ -26,7 +26,10 @@ import java.util.ArrayList; // TODO // - do we really need the .bits...? if not we can make util in UnicodeUtil to convert 1 char into a BytesRef -/** @lucene.internal */ +/** + * Converts UTF-32 automata to the equivalent UTF-8 representation. + * @lucene.internal + */ public final class UTF32ToUTF8 { // Unicode boundaries for UTF8 bytes 1,2,3,4 diff --git a/lucene/core/src/java/org/apache/lucene/util/fst/Util.java b/lucene/core/src/java/org/apache/lucene/util/fst/Util.java index 4eff7a55f1a..a398f87e637 100644 --- a/lucene/core/src/java/org/apache/lucene/util/fst/Util.java +++ b/lucene/core/src/java/org/apache/lucene/util/fst/Util.java @@ -497,7 +497,7 @@ public final class Util { } /** Holds a single input (IntsRef) + output, returned by - * {@link #shortestPaths}. */ + * {@link #shortestPaths shortestPaths()}. */ public final static class MinResult implements Comparable> { public final IntsRef input; public final T output;