fix javadoc

git-svn-id: https://svn.apache.org/repos/asf/lucene/dev/trunk@1356435 13f79535-47bb-0310-9956-ffa450edef68

lucene/analysis/common/src/java/org/apache/lucene/analysis/util/CharArrayMap.java

@@ -650,7 +650,7 @@ public class CharArrayMap<V> extends AbstractMap<Object,V> {
   }
   
   /**
-   * Empty {@link UnmodifiableCharArrayMap} optimized for speed.
+   * Empty {@link org.apache.lucene.analysis.util.CharArrayMap.UnmodifiableCharArrayMap} optimized for speed.
    * Contains checks will always return <code>false</code> or throw
    * NPE if necessary.
    */

lucene/analysis/common/src/test/org/apache/lucene/analysis/commongrams/CommonGramsFilterTest.java

@@ -81,7 +81,6 @@ public class CommonGramsFilterTest extends BaseTokenStreamTestCase {
    * "foo bar the"=>"foo:1|bar:2,bar-the:2|the:3=> "foo" "bar-the" (2 tokens
    * out)
    * 
-   * @return Map<String,String>
    */
   public void testCommonGramsQueryFilter() throws Exception {
     Analyzer a = new Analyzer() {

lucene/analysis/common/src/test/org/apache/lucene/analysis/shingle/ShingleAnalyzerWrapperTest.java

@@ -49,8 +49,6 @@ public class ShingleAnalyzerWrapperTest extends BaseTokenStreamTestCase {
   /**
    * Set up a new index in RAM with three test phrases and the supplied Analyzer.
    *
-   * @param analyzer the analyzer to use
-   * @return an indexSearcher on the test index.
    * @throws Exception if an error occurs with index writer or searcher
    */
   @Override

lucene/analysis/phonetic/src/java/org/apache/lucene/analysis/phonetic/BeiderMorseFilter.java

@@ -62,9 +62,13 @@ public final class BeiderMorseFilter extends TokenFilter {
   private final PositionIncrementAttribute posIncAtt = addAttribute(PositionIncrementAttribute.class);
   private final OffsetAttribute offsetAtt = addAttribute(OffsetAttribute.class);
   
+  
   /**
-   * Calls {@link #BeiderMorseFilter(TokenStream, PhoneticEngine, Languages.LanguageSet)
+   * Calls
-   *        BeiderMorseFilter(input, engine, null)}
+   * {@link #BeiderMorseFilter(TokenStream, PhoneticEngine, org.apache.commons.codec.language.bm.Languages.LanguageSet)}
+   * 
+   * @param input
+   * @param engine
    */
   public BeiderMorseFilter(TokenStream input, PhoneticEngine engine) {
     this(input, engine, null);

lucene/analysis/phonetic/src/java/org/apache/lucene/analysis/phonetic/PhoneticFilter.java

@@ -27,9 +27,8 @@ import java.io.IOException;
 
 /**
  * Create tokens for phonetic matches.
- * @see <a href="
+ * @see <a href="http://commons.apache.org/codec/api-release/org/apache/commons/codec/language/package-summary.html">
- * http://commons.apache.org/codec/api-release/org/apache/commons/codec/language/package-summary.html
+ * Apache Commons Codec</a>
- * ">Apache Commons Codec</a>
  */
 public final class PhoneticFilter extends TokenFilter 
 {

lucene/core/src/java/org/apache/lucene/codecs/lucene40/values/Writer.java

@@ -83,7 +83,7 @@ abstract class Writer extends DocValuesConsumer {
    *          docvalues of type {@link Type#BYTES_FIXED_SORTED} and
    *          {@link Type#BYTES_VAR_SORTED}.
    * @return a new {@link Writer} instance for the given {@link Type}
-   * @see PackedInts#getReader(org.apache.lucene.store.DataInput, float)
+   * @see PackedInts#getReader(org.apache.lucene.store.DataInput)
    */
   public static DocValuesConsumer create(Type type, String id, Directory directory,
       Comparator<BytesRef> comp, Counter bytesUsed, IOContext context, float acceptableOverheadRatio) {

lucene/core/src/java/org/apache/lucene/index/CompositeReaderContext.java

@@ -61,7 +61,7 @@ public final class CompositeReaderContext extends IndexReaderContext {
   }
 
   @Override
-  public List<AtomicReaderContext> leaves() {
+  public List<AtomicReaderContext> leaves() throws UnsupportedOperationException {
     if (!isTopLevel)
       throw new UnsupportedOperationException("This is not a top-level context.");
     assert leaves != null;

lucene/core/src/java/org/apache/lucene/index/DocValues.java

@@ -208,7 +208,6 @@ public abstract class DocValues implements Closeable {
      * Returns a {@link BytesRef} for the given document id or throws an
      * {@link UnsupportedOperationException} if this source doesn't support
      * <tt>byte[]</tt> values.
-     * @throws IOException 
      * 
      * @throws UnsupportedOperationException
      *           if this source doesn't support <tt>byte[]</tt> values.

lucene/core/src/java/org/apache/lucene/index/IndexReader.java

@@ -52,7 +52,7 @@ import org.apache.lucene.util.BytesRef;
  
  <p>IndexReader instances for indexes on disk are usually constructed
  with a call to one of the static <code>DirectoryReader.open()</code> methods,
- e.g. {@link DirectoryReader#open(Directory)}. {@link DirectoryReader} implements
+ e.g. {@link DirectoryReader#open(org.apache.lucene.store.Directory)}. {@link DirectoryReader} implements
  the {@link CompositeReader} interface, it is not possible to directly get postings.
 
  <p> For efficiency, in this API documents are often referred to via

lucene/core/src/java/org/apache/lucene/index/IndexReaderContext.java

@@ -52,10 +52,10 @@ public abstract class IndexReaderContext {
    * returns itself as the only leaf.
    * <p>Note: this is convenience method since leaves can always be obtained by
    * walking the context tree using {@link #children()}.
-   * @throws UnsupportedOperationExceception if this is not a top-level context.
+   * @throws UnsupportedOperationException if this is not a top-level context.
    * @see #children()
    */
-  public abstract List<AtomicReaderContext> leaves();
+  public abstract List<AtomicReaderContext> leaves() throws UnsupportedOperationException;
   
   /**
    * Returns the context's children iff this context is a composite context

lucene/core/src/java/org/apache/lucene/index/IndexWriter.java

@@ -275,8 +275,7 @@ public class IndexWriter implements Closeable, TwoPhaseCommit {
    * the writer nor calling {@link #commit}.
    *
    * <p>Note that this is functionally equivalent to calling
-   * {#flush} and then using {@link IndexReader#open} to
+   * {#flush} and then opening a new reader.  But the turnaround time of this
-   * open a new reader.  But the turnaround time of this
    * method should be faster since it avoids the potentially
    * costly {@link #commit}.</p>
    *
@@ -1448,11 +1447,12 @@ public class IndexWriter implements Closeable, TwoPhaseCommit {
    * then any thread still running this method might hit a
    * {@link MergePolicy.MergeAbortedException}.
    *
+   * @param maxNumSegments maximum number of segments left
+   * 
    * @throws CorruptIndexException if the index is corrupt
    * @throws IOException if there is a low-level IO error
    * @see MergePolicy#findMerges
    *
-   * @param maxNumSegments maximum number of segments left
    * in the index after merging finishes
   */
   public void forceMerge(int maxNumSegments) throws IOException {
@@ -2002,11 +2002,11 @@ public class IndexWriter implements Closeable, TwoPhaseCommit {
   /**
    * Prepares the {@link SegmentInfo} for the new flushed segment and persists
    * the deleted documents {@link MutableBits}. Use
-   * {@link #publishFlushedSegment(SegmentInfo, FrozenBufferedDeletes, FrozenBufferedDeletes)} to
+   * {@link #publishFlushedSegment(SegmentInfoPerCommit, FrozenBufferedDeletes, FrozenBufferedDeletes)} to
    * publish the returned {@link SegmentInfo} together with its segment private
    * delete packet.
    * 
-   * @see #publishFlushedSegment(SegmentInfo, FrozenBufferedDeletes, FrozenBufferedDeletes)
+   * @see #publishFlushedSegment(SegmentInfoPerCommit, FrozenBufferedDeletes, FrozenBufferedDeletes)
    */
   SegmentInfoPerCommit prepareFlushedSegment(FlushedSegment flushedSegment) throws IOException {
     assert flushedSegment != null;

lucene/core/src/java/org/apache/lucene/search/FieldComparator.java

@@ -1063,12 +1063,12 @@ public abstract class FieldComparator<T> {
   
   /** Sorts by field's natural Term sort order, using
    *  ordinals.  This is functionally equivalent to {@link
-   *  TermValComparator}, but it first resolves the string
+   *  org.apache.lucene.search.FieldComparator.TermValComparator}, but it first resolves the string
    *  to their relative ordinal positions (using the index
    *  returned by {@link FieldCache#getTermsIndex}), and
    *  does most comparisons using the ordinals.  For medium
    *  to large results, this comparator will be much faster
-   *  than {@link TermValComparator}.  For very small
+   *  than {@link org.apache.lucene.search.FieldComparator.TermValComparator}.  For very small
    *  result sets it may be slower. */
   public static final class TermOrdValComparator extends FieldComparator<BytesRef> {
     /* Ords for each slot.
@@ -1469,7 +1469,7 @@ public abstract class FieldComparator<T> {
 
   /** Sorts by field's natural Term sort order, using
    *  ordinals; this is just like {@link
-   *  TermOrdValComparator} except it uses DocValues to
+   *  org.apache.lucene.search.FieldComparator.TermValComparator} except it uses DocValues to
    *  retrieve the sort ords saved during indexing. */
   public static final class TermOrdValDocValuesComparator extends FieldComparator<BytesRef> {
     /* Ords for each slot.

lucene/core/src/java/org/apache/lucene/search/similarities/Similarity.java

@@ -99,7 +99,7 @@ import org.apache.lucene.util.SmallFloat; // javadoc
  * </ol>
  * <p>
  * <a name="explaintime"/>
- * When {@link IndexSearcher#explain(Query, int)} is called, queries consult the Similarity's DocScorer for an 
+ * When {@link IndexSearcher#explain(org.apache.lucene.search.Query, int)} is called, queries consult the Similarity's DocScorer for an 
  * explanation of how it computed its score. The query passes in a the document id and an explanation of how the frequency
  * was computed.
  *

lucene/core/src/java/org/apache/lucene/search/similarities/TFIDFSimilarity.java

@@ -611,7 +611,6 @@ public abstract class TFIDFSimilarity extends Similarity {
    * @param termStats term-level statistics for the term
    * @return an Explain object that includes both an idf score factor 
              and an explanation for the term.
-   * @throws IOException
    */
   public Explanation idfExplain(CollectionStatistics collectionStats, TermStatistics termStats) {
     final long df = termStats.docFreq();
@@ -632,7 +631,6 @@ public abstract class TFIDFSimilarity extends Similarity {
    * @return an Explain object that includes both an idf 
    *         score factor for the phrase and an explanation 
    *         for each term.
-   * @throws IOException
    */
   public Explanation idfExplain(CollectionStatistics collectionStats, TermStatistics termStats[]) {
     final long max = collectionStats.maxDoc();

lucene/core/src/java/org/apache/lucene/util/packed/PackedInts.java

@@ -429,9 +429,6 @@ public class PackedInts {
    * @param acceptableOverheadRatio an acceptable overhead
    *        ratio per value
    * @return a mutable packed integer array
-   * @throws java.io.IOException if the Mutable could not be created. With the
-   *         current implementations, this never happens, but the method
-   *         signature allows for future persistence-backed Mutables.
    * @lucene.internal
    */
   public static Mutable getMutable(int valueCount,

lucene/core/src/test/org/apache/lucene/index/TestCrashCausesCorruptIndex.java

@@ -117,7 +117,6 @@ public class TestCrashCausesCorruptIndex extends LuceneTestCase  {
    * Run an example search.
    * 
    * @throws IOException
-   * @throws ParseException
    */
   private void searchForFleas(final int expectedTotalHits) throws IOException {
     Directory realDirectory = newFSDirectory(path);

lucene/core/src/test/org/apache/lucene/search/similarities/TestSimilarityBase.java

@@ -48,7 +48,7 @@ import org.apache.lucene.util.LuceneTestCase;
  * items in the list. If a test case fails, the name of the Similarity that
  * caused the failure is returned as part of the assertion error message.</p>
  * <p>Unit testing is performed by constructing statistics manually and calling
- * the {@link SimilarityBase#score(BasicStats, float, int)} method of the
+ * the {@link SimilarityBase#score(BasicStats, float, float)} method of the
  * Similarities. The statistics represent corner cases of corpus distributions.
  * </p>
  * <p>For the integration tests, a small (8-document) collection is indexed. The
@@ -181,7 +181,7 @@ public class TestSimilarityBase extends LuceneTestCase {
   }
   /**
    * The generic test core called by all unit test methods. It calls the
-   * {@link SimilarityBase#score(BasicStats, float, int)} method of all
+   * {@link SimilarityBase#score(BasicStats, float, float)} method of all
    * Similarities in {@link #sims} and checks if the score is valid; i.e. it
    * is a finite positive real number.
    */
@@ -513,7 +513,7 @@ public class TestSimilarityBase extends LuceneTestCase {
   
   /**
    * The generic test core called by all correctness test methods. It calls the
-   * {@link SimilarityBase#score(BasicStats, float, int)} method of all
+   * {@link SimilarityBase#score(BasicStats, float, float)} method of all
    * Similarities in {@link #sims} and compares the score against the manually
    * computed {@code gold}.
    */

lucene/core/src/test/org/apache/lucene/util/TestBytesRefHash.java

@@ -91,7 +91,7 @@ public class TestBytesRefHash extends LuceneTestCase {
 
   /**
    * Test method for
-   * {@link org.apache.lucene.util.BytesRefHash#get(org.apache.lucene.util.BytesRefHash.Entry)}
+   * {@link org.apache.lucene.util.BytesRefHash#get(int, BytesRef)}
    * .
    */
   @Test

lucene/queryparser/src/java/org/apache/lucene/queryparser/surround/query/SrndQuery.java

@@ -73,7 +73,7 @@ public abstract class SrndQuery implements Cloneable {
   /** For subclasses of {@link SrndQuery} within the package
    *  {@link org.apache.lucene.queryparser.surround.query}
    *  it is not necessary to override this method,
-   *  @see #toString().
+   *  @see #toString()
    */
   @Override
   public int hashCode() {
@@ -83,7 +83,7 @@ public abstract class SrndQuery implements Cloneable {
   /** For subclasses of {@link SrndQuery} within the package
    *  {@link org.apache.lucene.queryparser.surround.query}
    *  it is not necessary to override this method,
-   *  @see #toString().
+   *  @see #toString()
    */
   @Override
   public boolean equals(Object obj) {

lucene/spatial/src/java/org/apache/lucene/spatial/query/SpatialOperation.java

@@ -26,7 +26,7 @@ import java.util.*;
  * A clause that compares a stored geometry to a supplied geometry.
  *
  * @see <a href="http://edndoc.esri.com/arcsde/9.1/general_topics/understand_spatial_relations.htm">
- *   ESRI's docs on spatial relations</a>
+ *   ESRIs docs on spatial relations</a>
  * @see <a href="http://docs.geoserver.org/latest/en/user/filter/ecql_reference.html#spatial-predicate">
  *   GeoServer ECQL Spatial Predicates</a>
  *

solr/contrib/extraction/src/java/org/apache/solr/handler/extraction/ExtractingDocumentLoader.java

@@ -114,8 +114,6 @@ public class ExtractingDocumentLoader extends ContentStreamLoader {
   /**
    * this must be MT safe... may be called concurrently from multiple threads.
    *
-   * @param
-   * @param
    */
   void doAdd(SolrContentHandler handler, AddUpdateCommand template)
           throws IOException {

solr/core/src/java/org/apache/solr/handler/SnapPuller.java

@@ -231,17 +231,18 @@ public class SnapPuller {
     }
   }
 
+  private boolean successfulInstall = false;
+
   /**
    * This command downloads all the necessary files from master to install a index commit point. Only changed files are
    * downloaded. It also downloads the conf files (if they are modified).
    *
    * @param core the SolrCore
+   * @param force force a replication in all cases 
    * @return true on success, false if slave is already in sync
    * @throws IOException if an exception occurs
    */
   @SuppressWarnings("unchecked")
-  private boolean successfulInstall = false;
-
   boolean fetchLatestIndex(SolrCore core, boolean force) throws IOException, InterruptedException {
     successfulInstall = false;
     replicationStartTime = System.currentTimeMillis();

solr/core/src/java/org/apache/solr/handler/component/StatsValuesFactory.java

@@ -429,11 +429,11 @@ class StringStatsValues extends AbstractStatsValues<String> {
   }
 
   /**
-   * Determines which of the given Strings is the maximum, as computed by {@link String#compareTo(Object)}
+   * Determines which of the given Strings is the maximum, as computed by {@link String#compareTo(String)}
    *
    * @param str1 String to compare against b
    * @param str2 String compared against a
-   * @return str1 if it is considered greater by {@link String#compareTo(Object)}, str2 otherwise
+   * @return str1 if it is considered greater by {@link String#compareTo(String)}, str2 otherwise
    */
   private static String max(String str1, String str2) {
     if (str1 == null) {
@@ -445,11 +445,11 @@ class StringStatsValues extends AbstractStatsValues<String> {
   }
 
   /**
-   * Determines which of the given Strings is the minimum, as computed by {@link String#compareTo(Object)}
+   * Determines which of the given Strings is the minimum, as computed by {@link String#compareTo(String)}
    *
    * @param str1 String to compare against b
    * @param str2 String compared against a
-   * @return str1 if it is considered less by {@link String#compareTo(Object)}, str2 otherwise
+   * @return str1 if it is considered less by {@link String#compareTo(String)}, str2 otherwise
    */
   private static String min(String str1, String str2) {
     if (str1 == null) {

solr/core/src/java/org/apache/solr/handler/component/TermVectorComponent.java

@@ -92,7 +92,7 @@ public class TermVectorComponent extends SearchComponent implements SolrCoreAwar
    * <p>
    * Does simple (non-glob-supporting) parsing on the 
    * {@link TermVectorParams#FIELDS} param if specified, otherwise it returns 
-   * the concrete field values specified in {@link CommonParams.FL} -- 
+   * the concrete field values specified in {@link CommonParams#FL} -- 
    * ignoring functions, transformers, or literals.  
    * </p>
    * <p>

solr/core/src/java/org/apache/solr/util/SimplePostTool.java

@@ -219,7 +219,6 @@ public class SimplePostTool {
   /**
    * Opens the file and posts it's contents to the solrUrl,
    * writes to response to output. 
-   * @throws UnsupportedEncodingException 
    */
   public void postFile(File file, OutputStream output, String type) {
 

solr/core/src/java/org/apache/solr/util/xslt/TransformerProvider.java

@@ -64,7 +64,7 @@ public class TransformerProvider {
   }
   
   /** Return a new Transformer, possibly created from our cached Templates object  
-   * @throws TransformerConfigurationException 
+   * @throws IOException 
    */ 
   public synchronized Transformer getTransformer(SolrConfig solrConfig, String filename,int cacheLifetimeSeconds) throws IOException {
     // For now, the Templates are blindly reloaded once cacheExpires is over.

solr/core/src/test/org/apache/solr/search/QueryEqualityTest.java

@@ -16,23 +16,17 @@ package org.apache.solr.search;
  * limitations under the License.
  */
 
-import org.apache.lucene.search.Query;
+import java.util.HashSet;
-import org.apache.lucene.search.Sort;
+import java.util.Set;
-import org.apache.lucene.search.SortField;
-import org.apache.lucene.search.QueryUtils;
 
+import org.apache.lucene.search.Query;
+import org.apache.lucene.search.QueryUtils;
 import org.apache.solr.SolrTestCaseJ4;
-import org.apache.solr.common.SolrException;
 import org.apache.solr.request.SolrQueryRequest;
 import org.apache.solr.request.SolrRequestInfo;
 import org.apache.solr.response.SolrQueryResponse;
-import org.apache.solr.schema.IndexSchema;
-
-import java.util.Set;
-import java.util.HashSet;
-
-import org.junit.BeforeClass;
 import org.junit.AfterClass;
+import org.junit.BeforeClass;
 
 
 
@@ -44,7 +38,7 @@ import org.junit.AfterClass;
  * {@link #testParserCoverage} until you add a new test method to this class.
  *
  * @see ValueSourceParser#standardValueSourceParsers
- * @see QParserPlugin.standardPlugins
+ * @see QParserPlugin#standardPlugins
  * @see QueryUtils
  **/
 public class QueryEqualityTest extends SolrTestCaseJ4 {
@@ -686,7 +680,7 @@ public class QueryEqualityTest extends SolrTestCaseJ4 {
    * the parser being tested for coverage sanity checking
    *
    * @see QueryUtils#check
-   * @see QueryUtils#checkEquals
+   * @see QueryUtils#checkEqual
    * @see #testParserCoverage
    */
   protected void assertQueryEquals(final String defType,

solr/solrj/src/java/org/apache/solr/client/solrj/impl/CloudSolrServer.java

@@ -104,9 +104,6 @@ public class CloudSolrServer extends SolrServer {
    * Connect to the zookeeper ensemble.
    * This is an optional method that may be used to force a connect before any other requests are sent.
    *
-   * @throws IOException
-   * @throws TimeoutException
-   * @throws InterruptedException
    */
   public void connect() {
     if (zkStateReader == null) {

solr/solrj/src/java/org/apache/solr/common/cloud/SolrZkClient.java

@@ -207,8 +207,8 @@ public class SolrZkClient {
   /**
    * @param path
    * @return true if path exists
-   * @throws KeeperException
    * @param retryOnConnLoss  
+   * @throws KeeperException
    * @throws InterruptedException
    */
   public Boolean exists(final String path, boolean retryOnConnLoss)

solr/solrj/src/java/org/apache/solr/common/cloud/ZkCmdExecutor.java

@@ -17,7 +17,6 @@ package org.apache.solr.common.cloud;
  * limitations under the License.
  */
 
-import java.io.IOException;
 import java.util.List;
 
 import org.apache.zookeeper.CreateMode;
@@ -51,10 +50,14 @@ public class ZkCmdExecutor {
     this.retryDelay = retryDelay;
   }
   
+
   /**
    * Perform the given operation, retrying if the connection fails
    * 
-   * @throws IOException 
+   * @param operation
+   * @return
+   * @throws KeeperException
+   * @throws InterruptedException
    */
   @SuppressWarnings("unchecked")
   public <T> T retryOperation(ZkOperation operation)

solr/solrj/src/java/org/apache/solr/common/cloud/ZkOperation.java

@@ -34,7 +34,6 @@ public abstract class ZkOperation {
      * @return the result of the operation or null
      * @throws KeeperException
      * @throws InterruptedException
-     * @throws IOException 
      */
     public abstract Object execute() throws KeeperException, InterruptedException;
 }