From 2c7dfa29bdda7de5b62ceba1fe1ac89bb7e70cae Mon Sep 17 00:00:00 2001
From: Chris Nauroth <cnauroth@apache.org>
Date: Mon, 17 Feb 2014 22:28:57 +0000
Subject: [PATCH] Fix javadoc in OfflineImageViewer. Contributed by Akira
 Ajisaka.

git-svn-id: https://svn.apache.org/repos/asf/hadoop/common/trunk@1569124 13f79535-47bb-0310-9956-ffa450edef68
---
 hadoop-hdfs-project/hadoop-hdfs/CHANGES.txt   |  2 ++
 .../tools/offlineImageViewer/LsrPBImage.java  | 30 ++++++-------------
 .../offlineImageViewer/PBImageXmlWriter.java  | 24 ++-------------
 3 files changed, 13 insertions(+), 43 deletions(-)

diff --git a/hadoop-hdfs-project/hadoop-hdfs/CHANGES.txt b/hadoop-hdfs-project/hadoop-hdfs/CHANGES.txt
index da99034bfe5..26ba5973149 100644
--- a/hadoop-hdfs-project/hadoop-hdfs/CHANGES.txt
+++ b/hadoop-hdfs-project/hadoop-hdfs/CHANGES.txt
@@ -416,6 +416,8 @@ Release 2.4.0 - UNRELEASED
     HDFS-5759. Web UI does not show up during the period of loading FSImage.
     (Haohui Mai via Arpit Agarwal)
 
+    HDFS-5942. Fix javadoc in OfflineImageViewer. (Akira Ajisaka via cnauroth)
+
   BREAKDOWN OF HDFS-5698 SUBTASKS AND RELATED JIRAS
 
     HDFS-5717. Save FSImage header in protobuf. (Haohui Mai via jing9)
diff --git a/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/tools/offlineImageViewer/LsrPBImage.java b/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/tools/offlineImageViewer/LsrPBImage.java
index 61c4d5e22ca..b6970571691 100644
--- a/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/tools/offlineImageViewer/LsrPBImage.java
+++ b/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/tools/offlineImageViewer/LsrPBImage.java
@@ -51,28 +51,16 @@ import com.google.common.collect.Maps;
 import com.google.common.io.LimitInputStream;
 
 /**
- * This is the tool for analyzing file sizes in the namespace image. In order to
- * run the tool one should define a range of integers <tt>[0, maxSize]</tt> by
- * specifying <tt>maxSize</tt> and a <tt>step</tt>. The range of integers is
- * divided into segments of size <tt>step</tt>:
- * <tt>[0, s<sub>1</sub>, ..., s<sub>n-1</sub>, maxSize]</tt>, and the visitor
- * calculates how many files in the system fall into each segment
- * <tt>[s<sub>i-1</sub>, s<sub>i</sub>)</tt>. Note that files larger than
- * <tt>maxSize</tt> always fall into the very last segment.
+ * LsrPBImage displays the blocks of the namespace in a format very similar
+ * to the output of ls/lsr.  Entries are marked as directories or not,
+ * permissions listed, replication, username and groupname, along with size,
+ * modification date and full path.
  *
- * <h3>Input.</h3>
- * <ul>
- * <li><tt>filename</tt> specifies the location of the image file;</li>
- * <li><tt>maxSize</tt> determines the range <tt>[0, maxSize]</tt> of files
- * sizes considered by the visitor;</li>
- * <li><tt>step</tt> the range is divided into segments of size step.</li>
- * </ul>
- *
- * <h3>Output.</h3> The output file is formatted as a tab separated two column
- * table: Size and NumFiles. Where Size represents the start of the segment, and
- * numFiles is the number of files form the image which size falls in this
- * segment.
- * 
+ * Note: A significant difference between the output of the lsr command
+ * and this image visitor is that this class cannot sort the file entries;
+ * they are listed in the order they are stored within the fsimage file. 
+ * Therefore, the output of this class cannot be directly compared to the
+ * output of the lsr command.
  */
 final class LsrPBImage {
   private final Configuration conf;
diff --git a/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/tools/offlineImageViewer/PBImageXmlWriter.java b/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/tools/offlineImageViewer/PBImageXmlWriter.java
index d70f63710b1..659f13394e2 100644
--- a/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/tools/offlineImageViewer/PBImageXmlWriter.java
+++ b/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/tools/offlineImageViewer/PBImageXmlWriter.java
@@ -55,28 +55,8 @@ import com.google.common.collect.Lists;
 import com.google.common.io.LimitInputStream;
 
 /**
- * This is the tool for analyzing file sizes in the namespace image. In order to
- * run the tool one should define a range of integers <tt>[0, maxSize]</tt> by
- * specifying <tt>maxSize</tt> and a <tt>step</tt>. The range of integers is
- * divided into segments of size <tt>step</tt>:
- * <tt>[0, s<sub>1</sub>, ..., s<sub>n-1</sub>, maxSize]</tt>, and the visitor
- * calculates how many files in the system fall into each segment
- * <tt>[s<sub>i-1</sub>, s<sub>i</sub>)</tt>. Note that files larger than
- * <tt>maxSize</tt> always fall into the very last segment.
- *
- * <h3>Input.</h3>
- * <ul>
- * <li><tt>filename</tt> specifies the location of the image file;</li>
- * <li><tt>maxSize</tt> determines the range <tt>[0, maxSize]</tt> of files
- * sizes considered by the visitor;</li>
- * <li><tt>step</tt> the range is divided into segments of size step.</li>
- * </ul>
- *
- * <h3>Output.</h3> The output file is formatted as a tab separated two column
- * table: Size and NumFiles. Where Size represents the start of the segment, and
- * numFiles is the number of files form the image which size falls in this
- * segment.
- *
+ * PBImageXmlWriter walks over an fsimage structure and writes out
+ * an equivalent XML document that contains the fsimage's components.
  */
 @InterfaceAudience.Private
 public final class PBImageXmlWriter {