HADOOP-399. Fix javadoc warnings. Contributed by Nigel.

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

CHANGES.txt

@@ -105,6 +105,8 @@ Trunk (unreleased changes)
     error.  Also, change the hadoop-daemon.sh script to rotate
     standard i/o log files.  (Raghu Angadi via cutting)
 
+29. HADOOP-399.  Fix javadoc warnings.  (Nigel Daley via cutting)
+
 
 Release 0.7.2 - 2006-10-18
 

src/examples/org/apache/hadoop/examples/ExampleDriver.java

@@ -19,15 +19,13 @@
 package org.apache.hadoop.examples;
 import org.apache.hadoop.util.ProgramDriver;
 
+/**
+ * A description of an example program based on its class and a 
+ * human-readable description.
+ * @author Owen O'Malley
+ */
 public class ExampleDriver {
   
-  /**
-   * A description of an example program based on its class and a 
-   * human-readable description.
-   * @author Owen O'Malley
-   * @date april 2006
-   */
-    
     public static void main(String argv[]){
         ProgramDriver pgd = new ProgramDriver();
         try {

src/examples/org/apache/hadoop/examples/PiBenchmark.java

@@ -58,7 +58,7 @@ public class PiBenchmark {
     
     /** Map method.
      * @param key
-     * @param value not-used.
+     * @param val not-used
      * @param out
      * @param reporter
      */
@@ -101,7 +101,7 @@ public class PiBenchmark {
           conf = job;
       }
       /** Reduce method.
-       * @ param key
+       * @param key
        * @param values
        * @param output
        * @param reporter

src/java/org/apache/hadoop/conf/Configuration.java

@@ -58,7 +58,7 @@ import org.apache.hadoop.fs.Path;
  * This String is processed for <b>variable expansion</b>. The available variables are the 
  * <em>System properties</em> and the <em>other properties</em> defined in this Configuration.
  * <p>The only <tt>get*</tt> method that is not processed for variable expansion is
- * {@link getObject} (as it cannot assume that the returned values are String). 
+ * {@link #getObject(String)} (as it cannot assume that the returned values are String). 
  * You can use <tt>getObject</tt> to obtain the raw value of a String property without 
  * variable expansion: if <tt>(String)conf.getObject("my.jdk")</tt> is <tt>"JDK ${java.version}"</tt>
  * then conf.get("my.jdk")</tt> is <tt>"JDK 1.5.0"</tt> 

src/java/org/apache/hadoop/dfs/DFSShell.java

@@ -191,12 +191,12 @@ public class DFSShell extends ToolBase {
     /**
      * Set the replication for files that match file pattern <i>srcf</i>
      * if it's a directory and recursive is true,
-     * set replication for all the subdirs and those files too
-     * @param newRep: new replication factor
-     * @param srcf: a file pattern specifying source files
-     * @param recursive: if need to set replication factor for files in subdirs
-     * @exception: IOException  
-     * @see org.apache.hadoop.fs.FileSystem.globPaths 
+     * set replication for all the subdirs and those files too.
+     * @param newRep new replication factor
+     * @param srcf a file pattern specifying source files
+     * @param recursive if need to set replication factor for files in subdirs
+     * @throws IOException  
+     * @see org.apache.hadoop.fs.FileSystem#globPaths(Path)
      */
     public void setReplication(short newRep, String srcf, boolean recursive)
         throws IOException {
@@ -248,11 +248,11 @@ public class DFSShell extends ToolBase {
     
     
     /**
-     * Get a listing of all files in DFS that match the file pattern <i>srcf</i>
-     * @param srcf: a file pattern specifying source files
-     * @param recursive: if need to list files in subdirs
-     * @exception: IOException  
-     * @see org.apache.hadoop.fs.FileSystem.globPaths 
+     * Get a listing of all files in DFS that match the file pattern <i>srcf</i>.
+     * @param srcf a file pattern specifying source files
+     * @param recursive if need to list files in subdirs
+     * @throws IOException  
+     * @see org.apache.hadoop.fs.FileSystem#globPaths(Path)
      */
     public void ls(String srcf, boolean recursive) throws IOException {
       Path[] srcs = fs.globPaths( new Path(srcf) );
@@ -286,10 +286,10 @@ public class DFSShell extends ToolBase {
     }
 
     /**
-     * Show the size of all files in DFS that match the file pattern <i>srcf</i>
-     * @param srcf: a file pattern specifying source files
-     * @exception: IOException  
-     * @see org.apache.hadoop.fs.FileSystem.globPaths 
+     * Show the size of all files in DFS that match the file pattern <i>src</i>
+     * @param src a file pattern specifying source files
+     * @throws IOException  
+     * @see org.apache.hadoop.fs.FileSystem#globPaths(Path)
      */
     public void du(String src) throws IOException {
         Path items[] = fs.listPaths( fs.globPaths( new Path(src) ) );
@@ -317,10 +317,10 @@ public class DFSShell extends ToolBase {
      * to a destination dfs file.
      * When moving mutiple files, the destination must be a directory. 
      * Otherwise, IOException is thrown.
-     * @param srcf: a file pattern specifying source files
-     * @param dstf: a destination local file/directory 
-     * @exception: IOException  
-     * @see org.apache.hadoop.fs.FileSystem.globPaths 
+     * @param srcf a file pattern specifying source files
+     * @param dstf a destination local file/directory 
+     * @throws IOException  
+     * @see org.apache.hadoop.fs.FileSystem#globPaths(Path)
      */
     public void rename(String srcf, String dstf) throws IOException {
       Path [] srcs = fs.globPaths( new Path(srcf) );
@@ -403,10 +403,10 @@ public class DFSShell extends ToolBase {
      * to a destination dfs file.
      * When copying mutiple files, the destination must be a directory. 
      * Otherwise, IOException is thrown.
-     * @param srcf: a file pattern specifying source files
-     * @param dstf: a destination local file/directory 
-     * @exception: IOException  
-     * @see org.apache.hadoop.fs.FileSystem.globPaths 
+     * @param srcf a file pattern specifying source files
+     * @param dstf a destination local file/directory 
+     * @throws IOException  
+     * @see org.apache.hadoop.fs.FileSystem#globPaths(Path)
      */
     public void copy(String srcf, String dstf, Configuration conf) throws IOException {
       Path [] srcs = fs.globPaths( new Path(srcf) );
@@ -481,11 +481,11 @@ public class DFSShell extends ToolBase {
     }
 
     /**
-     * Delete all files in DFS that match the file pattern <i>srcf</i>
-     * @param srcf: a file pattern specifying source files
-     * @param recursive: if need to delete subdirs
-     * @exception: IOException  
-     * @see org.apache.hadoop.fs.FileSystem.globPaths 
+     * Delete all files in DFS that match the file pattern <i>srcf</i>.
+     * @param srcf a file pattern specifying source files
+     * @param recursive if need to delete subdirs
+     * @throws IOException  
+     * @see org.apache.hadoop.fs.FileSystem#globPaths(Path)
      */
     public void delete(String srcf, boolean recursive) throws IOException {
       Path [] srcs = fs.globPaths( new Path(srcf) );

src/java/org/apache/hadoop/dfs/DFSck.java

@@ -38,11 +38,11 @@ import org.apache.hadoop.util.ToolBase;
  * <li>files with blocks that are completely missing from all datanodes.<br/>
  * In this case the tool can perform one of the following actions:
  *  <ul>
- *      <li>none ({@link #FIXING_NONE})</li>
+ *      <li>none ({@link NamenodeFsck#FIXING_NONE})</li>
  *      <li>move corrupted files to /lost+found directory on DFS
- *      ({@link #FIXING_MOVE}). Remaining data blocks are saved as a
+ *      ({@link NamenodeFsck#FIXING_MOVE}). Remaining data blocks are saved as a
  *      block chains, representing longest consecutive series of valid blocks.</li>
- *      <li>delete corrupted files ({@link #FIXING_DELETE})</li>
+ *      <li>delete corrupted files ({@link NamenodeFsck#FIXING_DELETE})</li>
  *  </ul>
  *  </li>
  *  <li>detect files with under-replicated or over-replicated blocks</li>

src/java/org/apache/hadoop/dfs/DatanodeProtocol.java

@@ -51,10 +51,10 @@ interface DatanodeProtocol extends VersionedProtocol {
   /** 
    * Register Datanode.
    *
-   * @see DataNode#register()
-   * @see FSNamesystem#registerDatanode(DatanodeRegistration)
+   * @see org.apache.hadoop.dfs.DataNode#register()
+   * @see org.apache.hadoop.dfs.FSNamesystem#registerDatanode(DatanodeRegistration)
    * 
-   * @return updated {@link DatanodeRegistration}, which contains 
+   * @return updated {@link org.apache.hadoop.dfs.DatanodeRegistration}, which contains 
    * new storageID if the datanode did not have one and
    * registration ID for further communication.
    */

src/java/org/apache/hadoop/dfs/DistributedFileSystem.java

@@ -258,10 +258,8 @@ public class DistributedFileSystem extends FileSystem {
     
     /**
      * Enter, leave or get safe mode.
-     * See {@link ClientProtocol#setSafeMode(FSConstants.SafeModeAction)} 
-     * for more details.
      *  
-     * @see ClientProtocol#setSafeMode(FSConstants.SafeModeAction)
+     * @see org.apache.hadoop.dfs.ClientProtocol#setSafeMode(FSConstants.SafeModeAction)
      */
     public boolean setSafeMode( FSConstants.SafeModeAction action ) 
     throws IOException {

src/java/org/apache/hadoop/dfs/NamenodeFsck.java

@@ -88,12 +88,11 @@ public class NamenodeFsck {
   
   /**
    * Filesystem checker.
-   * @param conf current Configuration
-   * @param fixing one of pre-defined values
-   * @param showFiles show each file being checked
-   * @param showBlocks for each file checked show its block information
-   * @param showLocations for each block in each file show block locations
-   * @throws Exception
+   * @param conf configuration (namenode config)
+   * @param nn namenode that this fsck is going to use
+   * @param pmap key=value[] map that is passed to the http servlet as url parameters
+   * @param response the object into which  this servelet writes the url contents
+   * @throws IOException
    */
   public NamenodeFsck(Configuration conf,
       NameNode nn,
@@ -457,7 +456,6 @@ public class NamenodeFsck {
     
     /**
      * DFS is considered healthy if there are no missing blocks.
-     * @return
      */
     public boolean isHealthy() {
       return missingIds.size() == 0;

src/java/org/apache/hadoop/fs/FileSystem.java

@@ -537,7 +537,7 @@ public abstract class FileSystem extends Configured {
 
     /** 
      * Filter raw files in a list directories using the default checksum filter. 
-     * @param files: a list of paths
+     * @param files a list of paths
      * @return a list of files under the source paths
      * @exception IOException
      */
@@ -547,7 +547,7 @@ public abstract class FileSystem extends Configured {
     
     /** 
      * Filter raw files in a list directories using user-supplied path filter. 
-     * @param files: a list of paths
+     * @param files a list of paths
      * @return a list of files under the source paths
      * @exception IOException
      */
@@ -604,7 +604,7 @@ public abstract class FileSystem extends Configured {
      *  </dd>
      * </dl>
      *
-     * @param filePattern: a regular expression specifying file pattern
+     * @param filePattern a regular expression specifying file pattern
 
      * @return an array of paths that match the file pattern
      * @throws IOException
@@ -614,8 +614,7 @@ public abstract class FileSystem extends Configured {
     }
     
     /** glob all the file names that matches filePattern
-     * and is accepted by filter
-     * @param 
+     * and is accepted by filter.
      */
     public Path[] globPaths(Path filePattern, PathFilter filter) 
         throws IOException {

src/java/org/apache/hadoop/fs/FileUtil.java

@@ -306,7 +306,7 @@ public class FileUtil {
    * Create a soft link between a src and destination
    * only on a local disk. HDFS does not support this
    * @param target the target for symlink 
-   * @param destination the symlink
+   * @param linkname the symlink
    * @return value returned by the command
    */
   public static int symLink(String target, String linkname) throws IOException{

src/java/org/apache/hadoop/fs/Path.java

@@ -123,7 +123,7 @@ public class Path implements Comparable {
     return new Path(isAbsolute, newElements, drive);
   }
 
-  /** Adds a suffix to a the final name in the path.*/
+  /** Adds a suffix to the final name in the path.*/
   public Path suffix(String suffix) {
     return new Path(getParent(), getName()+suffix);
   }

src/java/org/apache/hadoop/io/BytesWritable.java

@@ -60,7 +60,6 @@ public class BytesWritable implements WritableComparable {
   
   /**
    * Get the current size of the buffer.
-   * @return
    */
   public int getSize() {
     return size;

src/java/org/apache/hadoop/io/SequenceFile.java

@@ -56,7 +56,7 @@ public class SequenceFile {
   public static final int SYNC_INTERVAL = 100*SYNC_SIZE; 
 
   /** The type of compression.
-   * @see SequenceFile#Writer
+   * @see SequenceFile.Writer
    */
   public static enum CompressionType {
     /** Do not compress records. */
@@ -596,9 +596,9 @@ public class SequenceFile {
 
     /** Returns the current length of the output file.
      *
-     * <p>This always returns a synchronized position.  In other words, {@link
-     * immediately after calling {@link Reader#seek(long)} with a position
-     * returned by this method, Reader#next(Writable) may be called.  However
+     * <p>This always returns a synchronized position.  In other words,
+     * immediately after calling {@link SequenceFile.Reader#seek(long)} with a position
+     * returned by this method, {@link SequenceFile.Reader#next(Writable)} may be called.  However
      * the key may be earlier in the file than key last written when this
      * method was called (e.g., with block-compression, it may be the first key
      * in the block that was being written when this method was called).
@@ -1388,8 +1388,8 @@ public class SequenceFile {
     /** Set the current byte position in the input file.
      *
      * <p>The position passed must be a position returned by {@link
-     * Writer#getLength()} when writing this file.  To seek to an arbitrary
-     * position, use {@link Reader#sync(long)}.
+     * SequenceFile.Writer#getLength()} when writing this file.  To seek to an arbitrary
+     * position, use {@link SequenceFile.Reader#sync(long)}.
      */
     public synchronized void seek(long position) throws IOException {
       in.seek(position);

src/java/org/apache/hadoop/io/Text.java

@@ -96,7 +96,7 @@ public class Text implements WritableComparable {
    * Returns the Unicode Scalar Value (32-bit integer value)
    * for the character at <code>position</code>. Note that this
    * method avoids using the converter or doing String instatiation
-   * @returns the Unicode scalar value at position or -1
+   * @return the Unicode scalar value at position or -1
    *          if the position is invalid or points to a
    *          trailing byte
    */
@@ -410,8 +410,8 @@ public class Text implements WritableComparable {
 
   /** 
    * Check if a byte array contains valid utf-8
-   * @param utf8: byte array
-   * @exception MalformedInputException if the byte array contains invalid utf-8
+   * @param utf8 byte array
+   * @throws MalformedInputException if the byte array contains invalid utf-8
    */
   public static void validateUTF8(byte[] utf8) throws MalformedInputException {
      validateUTF8(utf8, 0, utf8.length);     

src/java/org/apache/hadoop/io/WritableUtils.java

@@ -336,10 +336,8 @@ public final class WritableUtils  {
 
   /**
    * Get the encoded length if an integer is stored in a variable-length format
-   * @param i: a long
    * @return the encoded length 
    */
-  
   public static int getVIntSize(long i) {
       if (i >= -112 && i <= 127) {
           return 1;

src/java/org/apache/hadoop/io/compress/CompressionInputStream.java

@@ -39,7 +39,7 @@ public abstract class CompressionInputStream extends InputStream {
   /**
    * Create a compression input stream that reads
    * the decompressed bytes from the given stream.
-   * @param out
+   * @param in
    */
   protected CompressionInputStream(InputStream in) {
     this.in = in;

src/java/org/apache/hadoop/mapred/FileSplit.java

@@ -30,7 +30,7 @@ import org.apache.hadoop.fs.Path;
 
 /** A section of an input file.  Returned by {@link
  * InputFormat#getSplits(FileSystem, JobConf, int)} and passed to
- * InputFormat#getRecordReader(FileSystem,FileSplit,JobConf,Reporter). */
+ * {@link InputFormat#getRecordReader(FileSystem,FileSplit,JobConf,Reporter)}. */
 public class FileSplit implements Writable {
   private Path file;
   private long start;

src/java/org/apache/hadoop/mapred/JobConf.java

@@ -73,7 +73,6 @@ public class JobConf extends Configuration {
 
   /** 
    * Construct a map/reduce job configuration.
-   * @param conf a Configuration whose settings will be inherited.
    * @param exampleClass a class whose containing jar is used as the job's jar.
    */
   public JobConf(Class exampleClass) {
@@ -83,8 +82,7 @@ public class JobConf extends Configuration {
   /**
    * Construct a map/reduce job configuration.
    * 
-   * @param conf
-   *          a Configuration whose settings will be inherited.
+   * @param conf a Configuration whose settings will be inherited.
    */
   public JobConf(Configuration conf) {
     super(conf);

src/java/org/apache/hadoop/mapred/JobHistory.java

@@ -225,7 +225,6 @@ public class JobHistory {
      * Convert value from history to int and return. 
      * if no value is found it returns 0.
      * @param k key 
-     * @return
      */
     public int getInt(Keys k){
       String s = values.get(k); 
@@ -238,7 +237,6 @@ public class JobHistory {
      * Convert value from history to int and return. 
      * if no value is found it returns 0.
      * @param k
-     * @return
      */
     public long getLong(Keys k){
       String s = values.get(k); 
@@ -271,7 +269,6 @@ public class JobHistory {
     }
     /**
      * Returns Map containing all key-values. 
-     * @return
      */
     public Map<Keys, String> getValues(){
       return values; 
@@ -292,7 +289,6 @@ public class JobHistory {
 
     /**
      * Returns all map and reduce tasks <taskid-Task>. 
-     * @return
      */
     public Map<String, Task> getAllTasks() { return allTasks; }
     
@@ -486,12 +482,12 @@ public class JobHistory {
     }
     /**
      * Returns all task attempts for this task. <task attempt id - TaskAttempt>
-     * @return
      */
     public Map<String, TaskAttempt> getTaskAttempts(){
       return this.taskAttempts;
     }
   }
+
   /**
    * Base class for Map and Reduce TaskAttempts. 
    */
@@ -745,4 +741,4 @@ public class JobHistory {
       isRunning = false ; 
     }
   }
-}
+}

src/java/org/apache/hadoop/mapred/SequenceFileInputFilter.java

@@ -107,8 +107,8 @@ public class SequenceFileInputFilter extends SequenceFileInputFormat {
     public static class RegexFilter extends FilterBase {
         private Pattern p;
         /** Define the filtering regex and stores it in conf
-         * @argument conf where the regex is set
-         * @argument regex regex used as a filter
+         * @param conf where the regex is set
+         * @param regex regex used as a filter
          */
         public static void setPattern(Configuration conf, String regex )
             throws PatternSyntaxException {

src/java/org/apache/hadoop/mapred/StatusHttpServer.java

@@ -103,10 +103,10 @@ public class StatusHttpServer {
   }
 
   /**
-   * Add a servlet in the server
+   * Add a servlet in the server.
    * @param name The name of the servlet (can be passed as null)
    * @param pathSpec The path spec for the servlet
-   * @param classname The class name for the servlet
+   * @param servletClass The servlet class
    */
   public <T extends HttpServlet> 
   void addServlet(String name, String pathSpec, 

src/java/org/apache/hadoop/mapred/TaskTracker.java

@@ -408,7 +408,6 @@ public class TaskTracker
     }
         
     /**Return the DFS filesystem
-     * @return
      */
     public FileSystem getFileSystem(){
       return fs;

src/java/org/apache/hadoop/util/ReflectionUtils.java

@@ -77,8 +77,8 @@ public class ReflectionUtils {
     }
     
     /**
-     * Print all of the thread's information and stack traces
-     * @author Owen O'Malley
+     * Print all of the thread's information and stack traces.
+     * 
      * @param stream the stream to
      * @param title a string title for the stack trace
      */

src/java/org/apache/hadoop/util/StringUtils.java

@@ -157,7 +157,6 @@ public class StringUtils {
   /**
    * 
    * @param uris
-   * @return
    */
   public static String uriToString(URI[] uris){
     String ret = null;
@@ -171,7 +170,6 @@ public class StringUtils {
   /**
    * 
    * @param str
-   * @return
    */
   public static URI[] stringToURI(String[] str){
     if (str == null) 
@@ -192,7 +190,6 @@ public class StringUtils {
   /**
    * 
    * @param str
-   * @return
    */
   public static Path[] stringToPath(String[] str){
     Path[] p = new Path[str.length];
@@ -208,8 +205,7 @@ public class StringUtils {
    * If finish time comes before start time then negative valeus of X, Y and Z wil return. 
    * 
    * @param finishTime finish time
-   * @param statTime start time
-   * @return
+   * @param startTime start time
    */
   public static String formatTimeDiff(long finishTime, long startTime){
     StringBuffer buf = new StringBuffer() ;

src/java/overview.html

@@ -134,7 +134,7 @@ cat ~/.ssh/id_dsa.pub >> ~/.ssh/authorized_keys
 
 <h3>Bootstrapping</h3>
 
-<p>A new distributed filesystem must formatted with the following
+<p>A new distributed filesystem must be formatted with the following
 command, run on the master node:</p>
 
 <p><tt>bin/hadoop namenode -format</tt></p>