minor cleanup of existing javadocs to reduce warnings

git-svn-id: https://svn.apache.org/repos/asf/incubator/solr/trunk@409791 13f79535-47bb-0310-9956-ffa450edef68

build.xml

@@ -26,6 +26,10 @@
   <property name="build.docs" value="${dest}/docs"/>
   <property name="javadoc.link.java"
             value="http://java.sun.com/j2se/1.5.0/docs/api/"/>
+  <property name="javadoc.link.junit"
+            value="http://junit.sourceforge.net/javadoc/"/>
+  <property name="javadoc.link.lucene"
+            value="http://lucene.apache.org/java/docs/api/"/>
   <property name="javadoc.packages" value="org.apache.solr.*"/>
   <property name="build.javadoc" value="${build.docs}/api"/>
 
@@ -96,6 +100,8 @@
         <packageset dir="${src}/java"/>
 	<packageset dir="${src}/webapp/src"/>
         <link href="${javadoc.link.java}"/>
+        <link href="${javadoc.link.junit}"/>
+        <link href="${javadoc.link.lucene}"/>
         <classpath refid="compile.classpath"/>
     </javadoc>
   </target>

src/java/org/apache/solr/core/Config.java

@@ -279,9 +279,16 @@ public class Config {
   }
 
   /**
-   * Returns a list of non-blank non-comment lines with whitespace trimmed from front and back.
+   * Accesses a resource by name and returns the (non comment) lines
+   * containing data.
+   *
+   * <p>
+   * A comment line is any line that starts with the character "#"
+   * </p>
+   *
    * @param resource
-   * @return
+   * @return a list of non-blank non-comment lines with whitespace trimmed
+   * from front and back.
    * @throws IOException
    */
   public static List<String> getLines(String resource) throws IOException {

src/java/org/apache/solr/core/SolrCore.java

@@ -289,7 +289,7 @@ public final class SolrCore {
    * searcher will be created.</li>
    * </ul>
    * <p>
-   * If <tt>returnSearcher==true</tt> then a {@link RefCounted}&lt{@link SolrIndexSearcher}&gt will be returned with
+   * If <tt>returnSearcher==true</tt> then a {@link RefCounted}&lt;{@link SolrIndexSearcher}&gt; will be returned with
    * the reference count incremented.  It <b>must</b> be decremented when no longer needed.
    * <p>
    * If <tt>waitSearcher!=null</tt> and a new {@link SolrIndexSearcher} was created,
@@ -298,9 +298,8 @@ public final class SolrCore {
    * this method returned.
    * <p>
    * @param forceNew           if true, force the open of a new index searcher regardless if there is already one open.
-   * @param returnSearcher     if true, returns a {@link &ltSolrIndexSearcher&gt} holder with the refcount already incremented.
+   * @param returnSearcher     if true, returns a {@link SolrIndexSearcher} holder with the refcount already incremented.
    * @param waitSearcher       if non-null, will be filled in with a {@link Future} that will return after the new searcher is registered.
-   * @return
    * @throws IOException
    */
   public RefCounted<SolrIndexSearcher> getSearcher(boolean forceNew, boolean returnSearcher, final Future[] waitSearcher) throws IOException {

src/java/org/apache/solr/search/QueryParsing.java

@@ -81,8 +81,8 @@ public class QueryParsing {
 
     /**
      * Gets the number of documens to return after sorting.
-     * -1 means there is no cutoff (only do the sort)
-     * @return
+     *
+     * @return number of docs to return, or -1 for no cut off (just sort)
      */
     public int getCount() { return num; }
   }

src/java/org/apache/solr/search/SolrIndexSearcher.java

@@ -470,10 +470,10 @@ public class SolrIndexSearcher extends Searcher implements SolrInfoMBean {
    * This method is cache-aware and attempts to retrieve the answer from the cache if possible.
    * If the answer was not cached, it may have been inserted into the cache as a result of this call.
    * <p>
-   * The DocSet returned should <b>not</b> be modified.
    *
    * @param query
    * @param filter may be null
+   * @return DocSet meeting the specified criteria, should <b>not</b> be modified by the caller.
    */
   public DocSet getDocSet(Query query, DocSet filter) throws IOException {
     if (filter==null) return getDocSet(query);
@@ -533,14 +533,12 @@ public class SolrIndexSearcher extends Searcher implements SolrInfoMBean {
    * <p>
    * FUTURE: The returned DocList may be retrieved from a cache.
    *
-   * The DocList returned should <b>not</b> be modified.
-   *
    * @param query
    * @param filter   may be null
    * @param lsort    criteria by which to sort (if null, query relevance is used)
    * @param offset   offset into the list of documents to return
    * @param len      maximum number of documents to return
-   * @return
+   * @return DocList meeting the specified criteria, should <b>not</b> be modified by the caller.
    * @throws IOException
    */
   public DocList getDocList(Query query, Query filter, Sort lsort, int offset, int len) throws IOException {
@@ -955,15 +953,13 @@ public class SolrIndexSearcher extends Searcher implements SolrInfoMBean {
    * Returns documents matching both <code>query</code> and <code>filter</code>
    * and sorted by <code>sort</code>.
    * FUTURE: The returned DocList may be retrieved from a cache.
-   * <p>
-   * The DocList returned should <b>not</b> be modified.
    *
    * @param query
    * @param filter   may be null
    * @param lsort    criteria by which to sort (if null, query relevance is used)
    * @param offset   offset into the list of documents to return
    * @param len      maximum number of documents to return
-   * @return
+   * @return DocList meeting the specified criteria, should <b>not</b> be modified by the caller.
    * @throws IOException
    */
   public DocList getDocList(Query query, DocSet filter, Sort lsort, int offset, int len) throws IOException {
@@ -989,7 +985,7 @@ public class SolrIndexSearcher extends Searcher implements SolrInfoMBean {
    * @param lsort    criteria by which to sort (if null, query relevance is used)
    * @param offset   offset into the list of documents to return
    * @param len      maximum number of documents to return
-   * @return
+   * @return DocListAndSet meeting the specified criteria, should <b>not</b> be modified by the caller.
    * @throws IOException
    */
   public DocListAndSet getDocListAndSet(Query query, Query filter, Sort lsort, int offset, int len) throws IOException {
@@ -1017,15 +1013,13 @@ public class SolrIndexSearcher extends Searcher implements SolrInfoMBean {
    * matching <code>query</code> and <code>filter</code> (regardless of <code>offset</code> and <code>len</code>).
    * <p>
    * FUTURE: The returned DocList may be retrieved from a cache.
-   * <p>
-   * The DocList and DocSet returned should <b>not</b> be modified.
    *
    * @param query
    * @param filter   may be null
    * @param lsort    criteria by which to sort (if null, query relevance is used)
    * @param offset   offset into the list of documents to return
    * @param len      maximum number of documents to return
-   * @return
+   * @return DocListAndSet meeting the specified criteria, should <b>not</b> be modified by the caller.
    * @throws IOException
    */
   public DocListAndSet getDocListAndSet(Query query, DocSet filter, Sort lsort, int offset, int len) throws IOException {

src/java/org/apache/solr/search/function/DocValues.java

@@ -21,8 +21,6 @@ import org.apache.lucene.search.Explanation;
 /**
  * Represents field values as different types.
  * Normally created via a {@link ValueSource} for a particular field and reader.
- * <br>
- * Often used by {@link FunctionFactory} implementations.
  *
  * @author yonik
  * @version $Id$

src/java/org/apache/solr/util/TestHarness.java

@@ -132,7 +132,7 @@ public class TestHarness {
    *
    * @param fieldsAndValues Odds are field names, Evens are values
    * @return null if succesful, otherwise the XML response to the update
-   * @see appendSimpleDoc
+   * @see #appendSimpleDoc
    */
   public String validateAddDoc(String... fieldsAndValues)
     throws XPathExpressionException, SAXException, IOException {