HADOOP-17981. review javadocs; reduce noisiness

Change-Id: I2bc9aefa0755ed68115526d5f6f3610d9eec6704

Author: steveloughran

hadoop-mapreduce-project/hadoop-mapreduce-client/hadoop-mapreduce-client-core/src/main/java/org/apache/hadoop/mapreduce/lib/output/FileOutputCommitter.java

@@ -804,12 +804,6 @@ private void mergePathsInParallel(FileSystem fs, final FileStatus from,
 
   /**
    * Rename the file via the resilient commit helper.
-   * Becquse any file at the destination will have been deleted,
-   * tell the commit helper that there is no need to probe the
-   * store for existance.
-   * This assumes that no two tasks created files with the same name,
-   * but so does any overwrite check performed nonatomically
-   * on the client.
    * @param from source filestatus
    * @param to destination path
    * @throws IOException failure to commit or rename.

hadoop-mapreduce-project/hadoop-mapreduce-client/hadoop-mapreduce-client-core/src/main/java/org/apache/hadoop/mapreduce/lib/output/ResilientCommitByRenameHelper.java

@@ -102,7 +102,7 @@ public boolean isRenameRecoveryAvailable() {
   }
 
   /**
-   * get count of rename failures recovered from.
+   * Get count of rename failures recovered from.
    * @return count of recoveries.
    */
   public int getRecoveryCount() {
@@ -128,8 +128,9 @@ public static boolean filesystemHasResilientCommmit(
 
   /**
    * Commit a file.
-   * Rename a file from source to dest; if the underlying FS API call
-   * returned false that's escalated to an IOE.
+   * Rename a file from source to dest with recovery attempted
+   * if the operation raises an exception/returns false, and
+   * recovery is enabled.
    * @param sourceStatus source status file
    * @param dest destination path
    * @return the outcome
@@ -141,10 +142,9 @@ public CommitOutcome commitFile(
       throws IOException {
     final Path source = sourceStatus.getPath();
     String operation = String.format("rename(%s, %s)", source, dest);
-    LOG.debug("{}", operation);
 
-    try (DurationInfo du = new DurationInfo(LOG, "%s with status %s",
-        operation, sourceStatus)) {
+    try (DurationInfo du = new DurationInfo(LOG, false,
+        "%s with status %s", operation, sourceStatus)) {
       if (operations.renameFile(source, dest)) {
         // success
         return new CommitOutcome();
@@ -226,7 +226,6 @@ private String getEtag(FileStatus status) {
 
   /**
    * Escalate a rename failure to an exception.
-   * This never returns
    * @param source source path
    * @param dest dest path
    * @return an exception to throw
@@ -265,6 +264,7 @@ public String toString() {
    * Outcome from the commit.
    */
   public static final class CommitOutcome {
+
     /**
      * Rename failed but etag checking concluded it finished.
      */
@@ -275,10 +275,18 @@ public static final class CommitOutcome {
      */
     private final IOException caughtException;
 
+    /**
+     * Success constructor.
+     */
     CommitOutcome() {
       this(false, null);
     }
 
+    /**
+     * Full constructor; used on failures.
+     * @param renameFailureResolvedThroughEtags was a rename failure recovered?
+     * @param caughtException Any exception caught before etag checking succeeded.
+     */
     CommitOutcome(
         boolean renameFailureResolvedThroughEtags,
         IOException caughtException) {
@@ -315,6 +323,10 @@ public static class FileSystemOperations {
      */
     private final FileSystem fileSystem;
 
+    /**
+     * Constructor.
+     * @param fileSystem filesystem to invoke.
+     */
     public FileSystemOperations(final FileSystem fileSystem) {
       this.fileSystem = fileSystem;
     }

hadoop-tools/hadoop-azure/src/test/java/org/apache/hadoop/fs/azurebfs/ITestAzureBlobFileSystemResilientCommit.java

@@ -58,6 +58,9 @@ public class ITestAzureBlobFileSystemResilientCommit
   private static final byte[] DATA = toAsciiByteArray("hello");
   private static final byte[] DATA2 = toAsciiByteArray("world");
 
+  /**
+   * is the test FS set up to raise exceptions on rename failures?
+   */
   private final boolean raiseExceptions;
 
   /**
@@ -160,7 +163,6 @@ public void testSimpleRename() throws Throwable {
           E_NO_SOURCE,
           () -> targetFS.rename(sourcePath, destPath));
     } else {
-
       Assertions.assertThat(targetFS.rename(sourcePath, destPath))
           .describedAs("return value of rename")
           .isFalse();
@@ -177,7 +179,6 @@ public void testSimpleRenameNoSource() throws Throwable {
           E_NO_SOURCE,
           () -> targetFS.rename(sourcePath, destPath));
     } else {
-
       Assertions.assertThat(targetFS.rename(sourcePath, destPath))
           .describedAs("return value of rename")
           .isFalse();
@@ -235,9 +236,9 @@ public void testDoubleCommitDifferentFiles() throws Throwable {
   }
 
   /**
-   * Commit a file, then
-   * try to commit again with a filestatus with a different source etag.
-   * Recovery will not report success.
+   * Commit a file, then try to commit again with a
+   * filestatus with a different source etag.
+   * Recovery MUST fail
    */
   @Test
   public void testDoubleCommitDifferentFiles2() throws Throwable {
@@ -263,7 +264,7 @@ public void testDoubleCommitDifferentFiles2() throws Throwable {
   }
 
   /**
-   * try to commit a file to a path where the destination
+   * Try to commit a file to a path where the destination
    * directory does not exist -expect an exception to
    * be raised.
    */
@@ -276,6 +277,10 @@ public void testCommitMissingDestDir() throws Throwable {
         commitHelper.commitFile(status, subpath));
   }
 
+  /**
+   * If there is no source and no destination, recovery
+   * MUST fail.
+   */
   @Test
   public void testCommitNoSource() throws Throwable {
     describe("delete the source file, expect commit to fail");