Did a bunch of comments cleanup.

git-svn-id: https://zxing.googlecode.com/svn/trunk@701 59b500cc-1b3d-0410-9834-0bbf25fbcc57

core/src/com/google/zxing/qrcode/encoder/MaskUtil.java

@@ -22,9 +22,8 @@ package com.google.zxing.qrcode.encoder;
  */
 public final class MaskUtil {
 
-  // The mask penalty calculation is complicated.  See Table 21 of
+  // The mask penalty calculation is complicated.  See Table 21 of JISX0510:2004 (p.45) for details.
-  // JISX0510:2004 (p.45) for details.  Basically it applies four
+  // Basically it applies four rules and summate all penalties.
-  // rules and summate all penalties.
   public static int CalculateMaskPenalty(final Matrix matrix) {
     int penalty = 0;
     penalty += ApplyMaskPenaltyRule1(matrix);
@@ -34,9 +33,8 @@ public final class MaskUtil {
     return penalty;
   }
 
-  // Apply mask penalty rule 1 and return the penalty.
+  // Apply mask penalty rule 1 and return the penalty. Find repetitive cells with the same color and
-  // Find repetitive cells with the same color and give penalty to
+  // give penalty to them. Example: 00000 or 11111.
-  // them.  Example: 00000 or 11111.
   public static int ApplyMaskPenaltyRule1(final Matrix matrix) {
     final int penalty = (ApplyMaskPenaltyRule1Internal(matrix, true) +
         ApplyMaskPenaltyRule1Internal(matrix, false));
@@ -44,8 +42,8 @@ public final class MaskUtil {
     return penalty;
   }
 
-  // Apply mask penalty rule 2 and return the penalty.
+  // Apply mask penalty rule 2 and return the penalty. Find 2x2 blocks with the same color and give
-  // Find 2x2 blocks with the same color and give penalty to them.
+  // penalty to them.
   //
   // JAVAPORT: Consider using Matrix.getArray() instead.
   public static int ApplyMaskPenaltyRule2(final Matrix matrix) {
@@ -64,9 +62,8 @@ public final class MaskUtil {
     return penalty;
   }
 
-  // Apply mask penalty rule 3 and return the penalty.
+  // Apply mask penalty rule 3 and return the penalty. Find consecutive cells of 00001011101 or
-  // Find consecutive cells of 00001011101 or 10111010000, and give
+  // 10111010000, and give penalty to them.  If we find patterns like 000010111010000, we give
-  // penalty to them.  If we find patterns like 000010111010000, we give
   // penalties twice (i.e. 40 * 2).
   //
   // JAVAPORT: This many calls to Matrix.get() looks expensive. We should profile and consider
@@ -122,10 +119,8 @@ public final class MaskUtil {
     return penalty;
   }
 
-  // Apply mask penalty rule 4 and return the penalty.
+  // Apply mask penalty rule 4 and return the penalty. Calculate the ratio of dark cells and give
-  // Calculate the ratio of dark cells and give penalty if the ratio
+  // penalty if the ratio is far from 50%. It gives 10 penalty for 5% distance. Examples:
-  // is far from 50%.  It gives 10 penalty for 5% distance.
-  // Examples:
   // -   0% => 100
   // -  40% =>  20
   // -  45% =>  10
@@ -149,8 +144,8 @@ public final class MaskUtil {
     return penalty;
   }
 
-  // Return the mask bit for "mask_pattern" at "x" and "y".
+  // Return the mask bit for "mask_pattern" at "x" and "y". See 8.8 of JISX0510:2004 for mask
-  // See 8.8 of JISX0510:2004 for mask pattern conditions.
+  // pattern conditions.
   public static int GetDataMaskBit(final int mask_pattern, final int x, final int y) {
     Debug.DCHECK(QRCode.IsValidMaskPattern(mask_pattern));
     switch (mask_pattern) {
@@ -177,9 +172,8 @@ public final class MaskUtil {
     return -1;
   }
 
-  // Helper function for ApplyMaskPenaltyRule1.  We need this for doing
+  // Helper function for ApplyMaskPenaltyRule1. We need this for doing this calculation in both
-  // this calculation in both vertical and horizontal orders
+  // vertical and horizontal orders respectively.
-  // respectively.
   private static int ApplyMaskPenaltyRule1Internal(final Matrix matrix, boolean is_horizontal) {
     int penalty = 0;
     int num_same_bit_cells = 0;

core/src/com/google/zxing/qrcode/encoder/MatrixUtil.java

@@ -50,8 +50,7 @@ public final class MatrixUtil {
       {1, 1, 1, 1, 1},
   };
 
-  // From Appendix E. Table 1, JIS0510X:2004 (p 71).
+  // From Appendix E. Table 1, JIS0510X:2004 (p 71). The table was double-checked by komatsu.
-  // The table was double-checked by komatsu.
   private static final int kPositionAdjustmentPatternCoordinateTable[][] = {
       {-1, -1, -1, -1,  -1,  -1,  -1},  // Version 1
       { 6, 18, -1, -1,  -1,  -1,  -1},  // Version 2
@@ -121,8 +120,7 @@ public final class MatrixUtil {
   private static final uint32 kTypeInfoPoly = 0x537;
   private static final uint32 kTypeInfoMaskPattern = 0x5412;
 
-  // Set all cells to -1.  -1 means that the cell is empty (not set
+  // Set all cells to -1.  -1 means that the cell is empty (not set yet).
-  // yet).
   public static void ClearMatrix(Matrix matrix) {
     for (int y = 0; y < matrix.height(); ++y) {
       for (int x = 0; x < matrix.width(); ++x) {
@@ -153,9 +151,8 @@ public final class MatrixUtil {
     return result.toString();
   }
 
-  // Build 2D matrix of QR Code from "data_bits" with "ec_level",
+  // Build 2D matrix of QR Code from "data_bits" with "ec_level", "version" and "mask_pattern". On
-  // "version" and "mask_pattern".  On success, store the result in
+  // success, store the result in "matrix" and return true.  On error, return false.
-  // "matrix" and return true.  On error, return false.
   public static boolean BuildMatrix(final BitVector &data_bits,
                                     int ec_level,
                                     int version,
@@ -177,8 +174,8 @@ public final class MatrixUtil {
     return EmbedDataBits(data_bits,  mask_pattern, matrix);
   }
 
-  // Embed basic patterns.  On success, modify the matrix and return
+  // Embed basic patterns. On success, modify the matrix and return true. On error, return false.
-  // true.  On error, return false.  The basic patterns are:
+  // The basic patterns are:
   // - Position detection patterns
   // - Timing patterns
   // - Dark dot at the left bottom corner
@@ -196,8 +193,7 @@ public final class MatrixUtil {
     return true;
   }
 
-  // Embed type information.  On success, modify the matrix and return
+  // Embed type information. On success, modify the matrix and return true. On error, return false.
-  // true.  On error, return false.
   public static boolean EmbedTypeInfo(int ec_level, int mask_pattern, Matrix matrix) {
     BitVector type_info_bits;
     if (!MakeTypeInfoBits(ec_level, mask_pattern, &type_info_bits)) {
@@ -206,12 +202,11 @@ public final class MatrixUtil {
     Debug.DCHECK_EQ(15, type_info_bits.size());
 
     for (int i = 0; i < type_info_bits.size(); ++i) {
-      // Place bits in LSB to MSB order.  LSB (least significant bit)
+      // Place bits in LSB to MSB order.  LSB (least significant bit) is the last value in
-      // is the last value in "type_info_bits".
+      // "type_info_bits".
       final int bit = type_info_bits.at(type_info_bits.size() - 1 - i);
 
-      // Type info bits at the left top corner.
+      // Type info bits at the left top corner. See 8.9 of JISX0510:2004 (p.46).
-      // See 8.9 of JISX0510:2004 (p.46).
       final int x1 = kTypeInfoCoordinates[i][0];
       final int y1 = kTypeInfoCoordinates[i][1];
       matrix.set(y1, x1, bit);
@@ -231,10 +226,9 @@ public final class MatrixUtil {
     return true;
   }
 
-  // Embed version information if need be.  On success, modify the
+  // Embed version information if need be. On success, modify the matrix and return true. On error,
-  // matrix and return true.  On error, return false.
+  // return false. See 8.10 of JISX0510:2004 (p.47) for how to embed version information. Return
-  // See 8.10 of JISX0510:2004 (p.47) for how to embed version
+  // true on success, otherwise return false.
-  // information.  Return true on success.  Return false otherwise.
   public static boolean MaybeEmbedVersionInfo(int version, Matrix matrix) {
     if (version < 7) {  // Version info is necessary if version >= 7.
       return true;  // Don't need version info.
@@ -259,9 +253,8 @@ public final class MatrixUtil {
     return true;
   }
 
-  // Embed "data_bits" using "mask_pattern".  On success, modify the
+  // Embed "data_bits" using "mask_pattern". On success, modify the matrix and return true. On
-  // matrix and return true.  On error, return false.  For debugging
+  // error, return false. For debugging purposes, it skips masking process if "mask_pattern" is -1.
-  // purpose, it skips masking process if "mask_pattern" is -1.
   // See 8.7 of JISX0510:2004 (p.38) for how to embed data bits.
   public static boolean EmbedDataBits(final BitVector &data_bits, int mask_pattern, Matrix matrix) {
     int bit_index = 0;
@@ -286,9 +279,8 @@ public final class MatrixUtil {
             bit = data_bits.at(bit_index);
             ++bit_index;
           } else {
-            // Padding bit.  If there is no bit left, we'll fill the
+            // Padding bit. If there is no bit left, we'll fill the left cells with 0, as described
-            // left cells with 0, as described in 8.4.9 of
+            // in 8.4.9 of JISX0510:2004 (p. 24).
-            // JISX0510:2004 (p. 24).
             bit = 0;
           }
           Debug.DCHECK(IsValidValue(bit));
@@ -316,10 +308,8 @@ public final class MatrixUtil {
     return true;
   }
 
-  // Return the position of the most significant bit set (to one) in
+  // Return the position of the most significant bit set (to one) in the "value". The most
-  // the "value".  The most significant bit is position 32.  If there
+  // significant bit is position 32. If there is no bit set, return 0. Examples:
-  // is no bit set, return 0.
-  // Examples:
   // - FindMSBSet(0) => 0
   // - FindMSBSet(1) => 1
   // - FindMSBSet(255) => 8
@@ -332,9 +322,8 @@ public final class MatrixUtil {
     return num_digits;
   }
 
-  // Calculate BCH (Bose-Chaudhuri-Hocquenghem) code for "value" using
+  // Calculate BCH (Bose-Chaudhuri-Hocquenghem) code for "value" using polynomial "poly". The BCH
-  // polynomial "poly".  The BCH code is used for encoding type
+  // code is used for encoding type information and version information.
-  // information and version information.
   // Example: Calculation of version information of 7.
   // f(x) is created from 7.
   //   - 7 = 000111 in 6 bits
@@ -356,12 +345,11 @@ public final class MatrixUtil {
   // Encode it in binary: 110010010100
   // The return value is 0xc94 (1100 1001 0100)
   //
-  // Since all coefficients in the polynomials are 1 or 0, we can do the
+  // Since all coefficients in the polynomials are 1 or 0, we can do the calculation by bit
-  // calculation by bit operations.  We don't care if cofficients are
+  // operations. We don't care if cofficients are positive or negative.
-  // positive or nagative.
   public static uint32 CalculateBCHCode(uint32 value, uint32 poly) {
-    // If poly is "1 1111 0010 0101" (version info poly),
+    // If poly is "1 1111 0010 0101" (version info poly), msb_set_in_poly is 13. We'll subtract 1
-    // msb_set_in_poly is 13.  We'll subtract 1 from 13 to make it 12.
+    // from 13 to make it 12.
     final int msb_set_in_poly = FindMSBSet(poly);
     value <<= msb_set_in_poly - 1;
     // Do the division business using exclusive-or operations.
@@ -372,9 +360,8 @@ public final class MatrixUtil {
     return value;
   }
 
-  // Make bit vector of type information.  On success, store the
+  // Make bit vector of type information. On success, store the result in "bits" and return true.
-  // result in "bits" and return true.  On error, return false.
+  // On error, return false. Encode error correction level and mask pattern. See 8.9 of
-  // Encode error correction level and mask pattern.  See 8.9 of
   // JISX0510:2004 (p.45) for details.
   public static boolean MakeTypeInfoBits(int ec_level, final int mask_pattern, BitVector *bits) {
     final int ec_code = QRCode.GetECLevelCode(ec_level);
@@ -402,10 +389,8 @@ public final class MatrixUtil {
     return true;
   }
 
-  // Make bit vector of version information.  On success, store the
+  // Make bit vector of version information. On success, store the result in "bits" and return true.
-  // result in "bits" and return true.  On error, return false.
+  // On error, return false. See 8.10 of JISX0510:2004 (p.45) for details.
-  // Encode version information.  See 8.10 of JISX0510:2004 (p.45) for
-  // details.
   public static boolean MakeVersionInfoBits(int version, BitVector *bits) {
     bits.AppendBits(version, 6);
     final uint32 bch_code = MatrixUtil.CalculateBCHCode(version,
@@ -431,9 +416,8 @@ public final class MatrixUtil {
   }
 
   private static void EmbedTimingPatterns(Matrix matrix) {
-    // -8 is for skipping position detection patterns (size 7), and
+    // -8 is for skipping position detection patterns (size 7), and two horizontal/vertical
-    // two horizontal/vertical separation patterns (size 1).
+    // separation patterns (size 1). Thus, 8 = 7 + 1.
-    // Thus, 8 = 7 + 1.
     for (int i = 8; i < matrix.width() - 8; ++i) {
       final int bit = (i + 1) % 2;
       // Horizontal line.
@@ -449,8 +433,7 @@ public final class MatrixUtil {
     }
   }
 
-  // Embed the lonely dark dot at left bottom corner.
+  // Embed the lonely dark dot at left bottom corner. JISX0510:2004 (p.46)
-  // JISX0510:2004 (p.46)
   private static void EmbedDarkDotAtLeftBottomCorner(Matrix matrix) {
     Debug.DCHECK(matrix.get(matrix.height() - 8, 8) != 0);
     matrix.set(matrix.height() - 8, 8, 1);
@@ -507,8 +490,7 @@ public final class MatrixUtil {
     }
   }
 
-  // Embed position detection patterns and surrounding
+  // Embed position detection patterns and surrounding vertical/horizontal separators.
-  // vertical/horizontal separators.
   private static void EmbedPositionDetectionPatternsAndSeparators(Matrix matrix) {
     // Embed three big squares at corners.
     final int pdp_width = arraysize(kPositionDetectionPattern[0]);
@@ -557,11 +539,10 @@ public final class MatrixUtil {
         if (x == -1 || y == -1) {
           continue;
         }
-        // If the cell is unset, we embed the position adjustment
+        // If the cell is unset, we embed the position adjustment pattern here.
-        // pattern here.
         if (IsEmpty(matrix.get(y, x))) {
-          // -2 is necessary since the x/y coordinates point to the
+          // -2 is necessary since the x/y coordinates point to the center of the pattern, not the
-          // center of the pattern, not the left top corner.
+          // left top corner.
           EmbedPositionAdjustmentPattern(x - 2, y - 2, matrix);
         }
       }

core/src/com/google/zxing/qrcode/encoder/QRCode.java

@@ -121,20 +121,8 @@ public final class QRCode {
   // Matrix data of the QR Code.
   public final Matrix matrix() { return matrix_; }
 
-  // Return the value of the module (cell) pointed by "x" and "y" in
+  // Return the value of the module (cell) pointed by "x" and "y" in the matrix of the QR Code. They
-  // the matrix of the QR Code.  They call cells in the matrix
+  // call cells in the matrix "modules". 1 represents a black cell, and 0 represents a white cell.
-  // "modules".  1 represents a black cell, and 0 represents a white
-  // cell.
-  //
-  // Note that the class internally used Array2D.  You should access
-  // cells in row-major order for cache efficiency.  Example:
-  //
-  //   for (int y = 0; y < qrcode.matrix_width(); ++y) {
-  //     for (int x = 0; x < qrcode.matrix_width(); ++x) {
-  //       DoSomething(qrcode.at(x, y));
-  //     }
-  //   }
-  //
   public int at(int x, int y) {
     // The value must be zero or one.
     int value = matrix_.get(y, x);
@@ -204,36 +192,68 @@ public final class QRCode {
     return result.toString();
   }
 
-  public void set_mode(int value) { mode_ = value; }
+  public void set_mode(int value) {
-  public void set_ec_level(int value) { ec_level_ = value; }
+    mode_ = value;
-  public void set_version(int value) { version_ = value; }
+  }
-  public void set_matrix_width(int value) { matrix_width_ = value; }
+
-  public void set_mask_pattern(int value) { mask_pattern_ = value; }
+  public void set_ec_level(int value) {
-  public void set_num_total_bytes(int value) { num_total_bytes_ = value; }
+    ec_level_ = value;
-  public void set_num_data_bytes(int value) { num_data_bytes_ = value; }
+  }
-  public void set_num_ec_bytes(int value) { num_ec_bytes_ = value; }
+
-  public void set_num_rs_blocks(int value) { num_rs_blocks_ = value; }
+  public void set_version(int value) {
+    version_ = value;
+  }
+
+  public void set_matrix_width(int value) {
+    matrix_width_ = value;
+  }
+
+  public void set_mask_pattern(int value) {
+    mask_pattern_ = value;
+  }
+
+  public void set_num_total_bytes(int value) {
+    num_total_bytes_ = value;
+  }
+
+  public void set_num_data_bytes(int value) {
+    num_data_bytes_ = value;
+  }
+
+  public void set_num_ec_bytes(int value) {
+    num_ec_bytes_ = value;
+  }
+
+  public void set_num_rs_blocks(int value) {
+    num_rs_blocks_ = value;
+  }
+
   // This takes ownership of the 2D array.  The 2D array will be
   // deleted in the destructor of the class.
-  public void set_matrix(Matrix value) { matrix_ = value; }
+  public void set_matrix(Matrix value) {
-
+    matrix_ = value;
+  }
 
   // Check if "version" is valid.
   public static boolean IsValidVersion(final int version) {
     return version >= kMinVersion && version <= kMaxVersion;
   }
+
   // Check if "mask_pattern" is valid.
   public static boolean IsValidECLevel(int ec_level) {
     return ec_level >= 0 && ec_level < NUM_EC_LEVELS;
   }
+
   // Check if "mode" is valid.
   public static boolean IsValidMode(final int mode) {
     return mode >= 0 && mode < NUM_MODES;
   }
+
   // Check if "width" is valid.
   public static boolean IsValidMatrixWidth(int width) {
     return width >= kMinMatrixWidth && width <= kMaxMatrixWidth;
   }
+
   // Check if "mask_pattern" is valid.
   public static boolean IsValidMaskPattern(int mask_pattern) {
     return mask_pattern >= 0 && mask_pattern < kNumMaskPatterns;
@@ -277,9 +297,8 @@ public final class QRCode {
     return "UNKNOWN";
   }
 
-  // Return the code of error correction level.  On error, return -1.
+  // Return the code of error correction level. On error, return -1. The codes of error correction
-  // The codes of error correction levels are defined in the table 22
+  // levels are defined in the table 22 of JISX0510:2004 (p.45).
-  // of JISX0510:2004 (p.45).
   public static int GetECLevelCode(final int ec_level) {
     switch (ec_level) {
       case QRCode.EC_LEVEL_L:
@@ -296,9 +315,8 @@ public final class QRCode {
     return -1;  // Unknown error correction level.
   }
 
-  // Return the code of mode.  On error, return -1.
+  // Return the code of mode. On error, return -1. The codes of modes are defined in the table 2 of
-  // The codes of modes are defined in the table 2 of JISX0510:2004
+  // JISX0510:2004 (p.16).
-  // (p.16).
   public static int GetModeCode(final int mode) {
     switch (mode) {
       case QRCode.MODE_NUMERIC:
@@ -315,8 +333,8 @@ public final class QRCode {
     return -1;  // Unknown mode.
   }
 
-  // Return the number of bits needed for representing the length info
+  // Return the number of bits needed for representing the length info of QR Code with "version" and
-  // of QR Code with "version" and "mode".  On error, return -1.
+  // "mode". On error, return -1.
   public static int GetNumBitsForLength(int version, int mode) {
     if (!IsValidVersion(version)) {
       Debug.LOG_ERROR("Invalid version: " + version);