Fix other Java 8 javadoc warnings

core/src/main/java/com/google/zxing/Binarizer.java

@@ -51,6 +51,7 @@ public abstract class Binarizer {
    * @param row An optional preallocated array. If null or too small, it will be ignored.
    *            If used, the Binarizer will call BitArray.clear(). Always use the returned object.
    * @return The array of bits for this row (true means black).
+   * @throws NotFoundException if row can't be binarized
    */
   public abstract BitArray getBlackRow(int y, BitArray row) throws NotFoundException;
 
@@ -61,6 +62,7 @@ public abstract class Binarizer {
    * fetched using getBlackRow(), so don't mix and match between them.
    *
    * @return The 2D array of bits for the image (true means black).
+   * @throws NotFoundException if image can't be binarized to make a matrix
    */
   public abstract BitMatrix getBlackMatrix() throws NotFoundException;
 

core/src/main/java/com/google/zxing/BinaryBitmap.java

@@ -60,6 +60,7 @@ public final class BinaryBitmap {
    * @param row An optional preallocated array. If null or too small, it will be ignored.
    *            If used, the Binarizer will call BitArray.clear(). Always use the returned object.
    * @return The array of bits for this row (true means black).
+   * @throws NotFoundException if row can't be binarized
    */
   public BitArray getBlackRow(int y, BitArray row) throws NotFoundException {
     return binarizer.getBlackRow(y, row);
@@ -72,6 +73,7 @@ public final class BinaryBitmap {
    * fetched using getBlackRow(), so don't mix and match between them.
    *
    * @return The 2D array of bits for the image (true means black).
+   * @throws NotFoundException if image can't be binarized to make a matrix
    */
   public BitMatrix getBlackMatrix() throws NotFoundException {
     // The matrix is created on demand the first time it is requested, then cached. There are two

core/src/main/java/com/google/zxing/Reader.java

@@ -37,7 +37,9 @@ public interface Reader {
    *
    * @param image image of barcode to decode
    * @return String which the barcode encodes
-   * @throws NotFoundException if the barcode cannot be located or decoded for any reason
+   * @throws NotFoundException if no potential barcode is found
+   * @throws ChecksumException if a potential barcode is found but does not pass its checksum
+   * @throws FormatException if a potential barcode is found but format is invalid
    */
   Result decode(BinaryBitmap image) throws NotFoundException, ChecksumException, FormatException;
 
@@ -51,7 +53,9 @@ public interface Reader {
    * meaning of the data depends upon the hint type. The implementation may or may not do
    * anything with these hints.
    * @return String which the barcode encodes
-   * @throws NotFoundException if the barcode cannot be located or decoded for any reason
+   * @throws NotFoundException if no potential barcode is found
+   * @throws ChecksumException if a potential barcode is found but does not pass its checksum
+   * @throws FormatException if a potential barcode is found but format is invalid
    */
   Result decode(BinaryBitmap image, Map<DecodeHintType,?> hints)
       throws NotFoundException, ChecksumException, FormatException;

core/src/main/java/com/google/zxing/ResultPoint.java

@@ -70,6 +70,8 @@ public class ResultPoint {
   /**
    * Orders an array of three ResultPoints in an order [A,B,C] such that AB is less than AC
    * and BC is less than AC, and the angle between BC and BA is less than 180 degrees.
+   *
+   * @param patterns array of three {@link ResultPoint} to order
    */
   public static void orderBestPatterns(ResultPoint[] patterns) {
 
@@ -113,6 +115,8 @@ public class ResultPoint {
 
 
   /**
+   * @param pattern1 first pattern
+   * @param pattern2 second pattern
    * @return distance between two points
    */
   public static float distance(ResultPoint pattern1, ResultPoint pattern2) {

core/src/main/java/com/google/zxing/Writer.java

@@ -34,17 +34,20 @@ public interface Writer {
    * @param format The barcode format to generate
    * @param width The preferred width in pixels
    * @param height The preferred height in pixels
+   * @return {@link BitMatrix} representing encoded barcode image
+   * @throws WriterException if contents cannot be encoded legally in a format
    */
   BitMatrix encode(String contents, BarcodeFormat format, int width, int height)
       throws WriterException;
 
   /**
-   *
    * @param contents The contents to encode in the barcode
    * @param format The barcode format to generate
    * @param width The preferred width in pixels
    * @param height The preferred height in pixels
    * @param hints Additional parameters to supply to the encoder
+   * @return {@link BitMatrix} representing encoded barcode image
+   * @throws WriterException if contents cannot be encoded legally in a format
    */
   BitMatrix encode(String contents,
                    BarcodeFormat format,

core/src/main/java/com/google/zxing/aztec/detector/Detector.java

@@ -55,6 +55,7 @@ public final class Detector {
   /**
    * Detects an Aztec Code in an image.
    *
+   * @param isMirror if true, image is a mirror-image of original
    * @return {@link AztecDetectorResult} encapsulating results of detecting an Aztec Code
    * @throws NotFoundException if no Aztec Code can be found
    */

core/src/main/java/com/google/zxing/aztec/encoder/AztecCode.java

@@ -32,7 +32,7 @@ public final class AztecCode {
   private BitMatrix matrix;
 
   /**
-   * Compact or full symbol indicator
+   * @return {@code true} if compact instead of full mode
    */
   public boolean isCompact() {
     return compact;
@@ -43,7 +43,7 @@ public final class AztecCode {
   }
 
   /**
-   * Size in pixels (width and height)
+   * @return size in pixels (width and height)
    */
   public int getSize() {
     return size;
@@ -54,7 +54,7 @@ public final class AztecCode {
   }
   
   /**
-   * Number of levels
+   * @return number of levels
    */
   public int getLayers() {
     return layers;
@@ -65,7 +65,7 @@ public final class AztecCode {
   }
 
   /**
-   * Number of data codewords
+   * @return number of data codewords
    */
   public int getCodeWords() {
     return codeWords;
@@ -76,7 +76,7 @@ public final class AztecCode {
   }
 
   /**
-   * The symbol image
+   * @return the symbol image
    */
   public BitMatrix getMatrix() {
     return matrix;

core/src/main/java/com/google/zxing/aztec/encoder/HighLevelEncoder.java

@@ -155,7 +155,7 @@ public final class HighLevelEncoder {
   }
 
   /**
-   * Convert the text represented by this High Level Encoder into a BitArray.
+   * @return text represented by this encoder encoded as a {@link BitArray}
    */
   public BitArray encode() {
     Collection<State> states = Collections.singletonList(State.INITIAL_STATE);

core/src/main/java/com/google/zxing/client/result/CalendarParsedResult.java

@@ -116,7 +116,7 @@ public final class CalendarParsedResult extends ParsedResult {
   }
 
   /**
-   * May return null if the event has no duration.
+   * @return event end {@link Date}, or {@code null} if event has no duration
    * @see #getStart()
    */
   public Date getEnd() {

core/src/main/java/com/google/zxing/client/result/ResultParser.java

@@ -71,6 +71,9 @@ public abstract class ResultParser {
    * Attempts to parse the raw {@link Result}'s contents as a particular type
    * of information (email, URL, etc.) and return a {@link ParsedResult} encapsulating
    * the result of parsing.
+   *
+   * @param theResult the raw {@link Result} to parse
+   * @return {@link ParsedResult} encapsulating the parsing result
    */
   public abstract ParsedResult parse(Result theResult);
 

core/src/main/java/com/google/zxing/common/BitArray.java

@@ -111,6 +111,8 @@ public final class BitArray implements Cloneable {
   }
 
   /**
+   * @param from index to start looking for unset bit
+   * @return index of next unset bit, or {@code size} if none are unset until the end
    * @see #getNextSet(int)
    */
   public int getNextUnset(int from) {
@@ -237,6 +239,9 @@ public final class BitArray implements Cloneable {
    * Appends the least-significant bits, from value, in order from most-significant to
    * least-significant. For example, appending 6 bits from 0x000001E will append the bits
    * 0, 1, 1, 1, 1, 0 in that order.
+   *
+   * @param value {@code int} containing bits to append
+   * @param numBits bits from value to append
    */
   public void appendBits(int value, int numBits) {
     if (numBits < 0 || numBits > 32) {

core/src/main/java/com/google/zxing/common/CharacterSetECI.java

@@ -95,9 +95,9 @@ public enum CharacterSetECI {
 
   /**
    * @param value character set ECI value
-   * @return CharacterSetECI representing ECI of given value, or null if it is legal but
+   * @return {@link CharacterSetECI} representing ECI of given value, or null if it is legal but
    *   unsupported
-   * @throws IllegalArgumentException if ECI value is invalid
+   * @throws FormatException if ECI value is invalid
    */
   public static CharacterSetECI getCharacterSetECIByValue(int value) throws FormatException {
     if (value < 0 || value >= 900) {

core/src/main/java/com/google/zxing/common/GridSampler.java

@@ -56,10 +56,29 @@ public abstract class GridSampler {
   }
 
   /**
-   * Samples an image for a rectangular matrix of bits of the given dimension.
+   * Samples an image for a rectangular matrix of bits of the given dimension. The sampling
+   * transformation is determined by the coordinates of 4 points, in the original and transformed
+   * image space.
+   *
    * @param image image to sample
    * @param dimensionX width of {@link BitMatrix} to sample from image
    * @param dimensionY height of {@link BitMatrix} to sample from image
+   * @param p1ToX point 1 preimage X
+   * @param p1ToY point 1 preimage Y
+   * @param p2ToX point 2 preimage X
+   * @param p2ToY point 2 preimage Y
+   * @param p3ToX point 3 preimage X
+   * @param p3ToY point 3 preimage Y
+   * @param p4ToX point 4 preimage X
+   * @param p4ToY point 4 preimage Y
+   * @param p1FromX point 1 image X
+   * @param p1FromY point 1 image Y
+   * @param p2FromX point 2 image X
+   * @param p2FromY point 2 image Y
+   * @param p3FromX point 3 image X
+   * @param p3FromY point 3 image Y
+   * @param p4FromX point 4 image X
+   * @param p4FromY point 4 image Y
    * @return {@link BitMatrix} representing a grid of points sampled from the image within a region
    *   defined by the "from" parameters
    * @throws NotFoundException if image can't be sampled, for example, if the transformation defined

core/src/main/java/com/google/zxing/common/PerspectiveTransform.java

@@ -83,7 +83,6 @@ public final class PerspectiveTransform {
     }
   }
 
-  /** Convenience method, not optimized for performance. */
   public void transformPoints(float[] xValues, float[] yValues) {
     int n = xValues.length;
     for (int i = 0; i < n; i ++) {

core/src/main/java/com/google/zxing/common/detector/MathUtils.java

@@ -24,6 +24,9 @@ public final class MathUtils {
   /**
    * Ends up being a bit faster than {@link Math#round(float)}. This merely rounds its
    * argument to the nearest int, where x.5 rounds up to x+1.
+   *
+   * @param d real value to round
+   * @return nearest {@code int}
    */
   public static int round(float d) {
     return (int) (d + 0.5f);

core/src/main/java/com/google/zxing/common/detector/WhiteRectangleDetector.java

@@ -48,6 +48,10 @@ public final class WhiteRectangleDetector {
   }
 
   /**
+   * @param image barcode image to find a rectangle in
+   * @param initSize initial size of search area around center
+   * @param x x position of search center
+   * @param y y position of search center
    * @throws NotFoundException if image is too small to accommodate {@code initSize}
    */
   public WhiteRectangleDetector(BitMatrix image, int initSize, int x, int y) throws NotFoundException {

core/src/main/java/com/google/zxing/oned/OneDReader.java

@@ -295,7 +295,9 @@ public abstract class OneDReader implements Reader {
    * @param row the black/white pixel data of the row
    * @param hints decode hints
    * @return {@link Result} containing encoded string and start/end of barcode
-   * @throws NotFoundException if an error occurs or barcode cannot be found
+   * @throws NotFoundException if no potential barcode is found
+   * @throws ChecksumException if a potential barcode is found but does not pass its checksum
+   * @throws FormatException if a potential barcode is found but format is invalid
    */
   public abstract Result decodeRow(int rowNumber, BitArray row, Map<DecodeHintType,?> hints)
       throws NotFoundException, ChecksumException, FormatException;

core/src/main/java/com/google/zxing/oned/OneDimensionalCodeWriter.java

@@ -95,8 +95,9 @@ public abstract class OneDimensionalCodeWriter implements Writer {
 
 
   /**
-   * Appends the given pattern to the target array starting at pos.
-   *
+   * @param target encode black/white pattern into this array
+   * @param pos position to start encoding at in {@code target}
+   * @param pattern lengths of black/white runs to encode
    * @param startColor starting color - false for white, true for black
    * @return the number of elements added to target.
    */
@@ -123,6 +124,7 @@ public abstract class OneDimensionalCodeWriter implements Writer {
    * Encode the contents to boolean array expression of one-dimensional barcode.
    * Start code and end code should be included in result, and side margins should not be included.
    *
+   * @param contents barcode contents to encode
    * @return a {@code boolean[]} of horizontal pixels (false = white, true = black)
    */
   public abstract boolean[] encode(String contents);

core/src/main/java/com/google/zxing/oned/UPCEANReader.java

@@ -132,6 +132,15 @@ public abstract class UPCEANReader extends OneDReader {
    * <p>Like {@link #decodeRow(int, BitArray, java.util.Map)}, but
    * allows caller to inform method about where the UPC/EAN start pattern is
    * found. This allows this to be computed once and reused across many implementations.</p>
+   *
+   * @param rowNumber row index into the image
+   * @param row encoding of the row of the barcode image
+   * @param startGuardRange start/end column where the opening start pattern was found
+   * @param hints optional hints that influence decoding
+   * @return {@link Result} encapsulating the result of decoding a barcode in the row
+   * @throws NotFoundException if no potential barcode is found
+   * @throws ChecksumException if a potential barcode is found but does not pass its checksum
+   * @throws FormatException if a potential barcode is found but format is invalid
    */
   public Result decodeRow(int rowNumber,
                           BitArray row,
@@ -232,9 +241,11 @@ public abstract class UPCEANReader extends OneDReader {
   }
 
   /**
+   * @param s string of digits to check
    * @return {@link #checkStandardUPCEANChecksum(CharSequence)}
+   * @throws FormatException if the string does not contain only digits
    */
-  boolean checkChecksum(String s) throws ChecksumException, FormatException {
+  boolean checkChecksum(String s) throws FormatException {
     return checkStandardUPCEANChecksum(s);
   }
 

core/src/main/java/com/google/zxing/oned/UPCEReader.java

@@ -17,7 +17,6 @@
 package com.google.zxing.oned;
 
 import com.google.zxing.BarcodeFormat;
-import com.google.zxing.ChecksumException;
 import com.google.zxing.FormatException;
 import com.google.zxing.NotFoundException;
 import com.google.zxing.common.BitArray;
@@ -88,7 +87,7 @@ public final class UPCEReader extends UPCEANReader {
   }
 
   @Override
-  protected boolean checkChecksum(String s) throws FormatException, ChecksumException {
+  protected boolean checkChecksum(String s) throws FormatException {
     return super.checkChecksum(convertUPCEtoUPCA(s));
   }
 

core/src/main/java/com/google/zxing/pdf417/PDF417Common.java

@@ -60,8 +60,7 @@ public final class PDF417Common {
   }
 
   /**
-   * Translate the symbol into a codeword.
-   *
+   * @param symbol encoded symbol to translate to a codeword
    * @return the codeword corresponding to the symbol.
    */
   public static int getCodeword(long symbol) {

core/src/main/java/com/google/zxing/pdf417/decoder/ec/ErrorCorrection.java

@@ -36,7 +36,11 @@ public final class ErrorCorrection {
   }
 
   /**
+   * @param received received codewords
+   * @param numECCodewords number of those codewords used for EC
+   * @param erasures location of erasures
    * @return number of errors
+   * @throws ChecksumException if errors cannot be corrected, maybe because of too many errors
    */
   public int decode(int[] received,
                     int numECCodewords,

core/src/main/java/com/google/zxing/pdf417/detector/Detector.java

@@ -65,6 +65,7 @@ public final class Detector {
   /**
    * <p>Detects a PDF417 Code in an image. Only checks 0 and 180 degree rotations.</p>
    *
+   * @param image barcode image to decode
    * @param hints optional hints to detector
    * @param multiple if true, then the image is searched for multiple codes. If false, then at most one code will
    * be found and returned

core/src/main/java/com/google/zxing/pdf417/encoder/PDF417.java

@@ -638,9 +638,9 @@ public final class PDF417 {
   }
 
   /**
-   * Generates the barcode logic.
-   *
-   * @param msg        the message to encode
+   * @param msg message to encode
+   * @param errorCorrectionLevel PDF417 error correction level to use
+   * @throws WriterException if the contents cannot be encoded in this format
    */
   public void generateBarcodeLogic(String msg, int errorCorrectionLevel) throws WriterException {
 
@@ -731,6 +731,11 @@ public final class PDF417 {
 
   /**
    * Sets max/min row/col values
+   *
+   * @param maxCols maximum allowed columns
+   * @param minCols minimum allowed columns
+   * @param maxRows maximum allowed rows
+   * @param minRows minimum allowed rows
    */
   public void setDimensions(int maxCols, int minCols, int maxRows, int minRows) {
     this.maxCols = maxCols;
@@ -740,21 +745,21 @@ public final class PDF417 {
   }
 
   /**
-   * Sets compaction to values stored in {@link Compaction} enum
+   * @param compaction compaction mode to use
    */
   public void setCompaction(Compaction compaction) {
     this.compaction = compaction;
   }
 
   /**
-   * Sets compact to be true or false
+   * @param compact if true, enables compaction
    */
   public void setCompact(boolean compact) {
     this.compact = compact;
   }
 
   /**
-   * Sets output encoding.
+   * @param encoding sets character encoding to use
    */
   public void setEncoding(Charset encoding) {
     this.encoding = encoding;

core/src/main/java/com/google/zxing/qrcode/decoder/Decoder.java

@@ -50,6 +50,7 @@ public final class Decoder {
    * "true" is taken to mean a black module.</p>
    *
    * @param image booleans representing white/black QR Code modules
+   * @param hints decoding hints that should be used to influence decoding
    * @return text and bytes encoded within the QR Code
    * @throws FormatException if the QR Code cannot be decoded
    * @throws ChecksumException if error correction fails
@@ -76,6 +77,7 @@ public final class Decoder {
    * <p>Decodes a QR Code represented as a {@link BitMatrix}. A 1 or "true" is taken to mean a black module.</p>
    *
    * @param bits booleans representing white/black QR Code modules
+   * @param hints decoding hints that should be used to influence decoding
    * @return text and bytes encoded within the QR Code
    * @throws FormatException if the QR Code cannot be decoded
    * @throws ChecksumException if error correction fails

core/src/main/java/com/google/zxing/qrcode/detector/Detector.java

@@ -54,20 +54,21 @@ public class Detector {
   }
 
   /**
-   * <p>Detects a QR Code in an image, simply.</p>
+   * <p>Detects a QR Code in an image.</p>
    *
    * @return {@link DetectorResult} encapsulating results of detecting a QR Code
-   * @throws NotFoundException if no QR Code can be found
+   * @throws NotFoundException if QR Code cannot be found
+   * @throws FormatException if a QR Code cannot be decoded
    */
   public DetectorResult detect() throws NotFoundException, FormatException {
     return detect(null);
   }
 
   /**
-   * <p>Detects a QR Code in an image, simply.</p>
+   * <p>Detects a QR Code in an image.</p>
    *
    * @param hints optional hints to detector
-   * @return {@link NotFoundException} encapsulating results of detecting a QR Code
+   * @return {@link DetectorResult} encapsulating results of detecting a QR Code
    * @throws NotFoundException if QR Code cannot be found
    * @throws FormatException if a QR Code cannot be decoded
    */
@@ -218,6 +219,11 @@ public class Detector {
   /**
    * <p>Computes an average estimated module size based on estimated derived from the positions
    * of the three finder patterns.</p>
+   *
+   * @param topLeft detected top-left finder pattern center
+   * @param topRight detected top-right finder pattern center
+   * @param bottomLeft detected bottom-left finder pattern center
+   * @return estimated module size
    */
   protected final float calculateModuleSize(ResultPoint topLeft,
                                             ResultPoint topRight,

core/src/main/java/com/google/zxing/qrcode/detector/FinderPatternFinder.java

@@ -476,6 +476,7 @@ public class FinderPatternFinder {
    * @param stateCount reading state module counts from horizontal scan
    * @param i row where finder pattern may be found
    * @param j end of possible finder pattern in row
+   * @param pureBarcode true if in "pure barcode" mode
    * @return true if a finder pattern candidate was found this time
    */
   protected final boolean handlePossibleCenter(int[] stateCount, int i, int j, boolean pureBarcode) {

core/src/main/java/com/google/zxing/qrcode/encoder/Encoder.java

@@ -62,15 +62,11 @@ public final class Encoder {
   }
 
   /**
-   *  Encode "bytes" with the error correction level "ecLevel". The encoding mode will be chosen
-   * internally by chooseMode(). On success, store the result in "qrCode".
-   *
-   * We recommend you to use QRCode.EC_LEVEL_L (the lowest level) for
-   * "getECLevel" since our primary use is to show QR code on desktop screens. We don't need very
-   * strong error correction for this purpose.
-   *
-   * Note that there is no way to encode bytes in MODE_KANJI. We might want to add EncodeWithMode()
-   * with which clients can specify the encoding mode. For now, we don't need the functionality.
+   * @param content text to encode
+   * @param ecLevel error correction level to use
+   * @return {@link QRCode} representing the encoded QR code
+   * @throws WriterException if encoding can't succeed, because of for example invalid content
+   *   or configuration
    */
   public static QRCode encode(String content, ErrorCorrectionLevel ecLevel) throws WriterException {
     return encode(content, ecLevel, null);