You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pdfbox.apache.org by le...@apache.org on 2018/02/06 18:08:35 UTC
pdfbox-jbig2 git commit: PDFBOX-4098: fixed some javadoc issues
Repository: pdfbox-jbig2
Updated Branches:
refs/heads/master b646848a1 -> 4713f7f34
PDFBOX-4098: fixed some javadoc issues
Project: http://git-wip-us.apache.org/repos/asf/pdfbox-jbig2/repo
Commit: http://git-wip-us.apache.org/repos/asf/pdfbox-jbig2/commit/4713f7f3
Tree: http://git-wip-us.apache.org/repos/asf/pdfbox-jbig2/tree/4713f7f3
Diff: http://git-wip-us.apache.org/repos/asf/pdfbox-jbig2/diff/4713f7f3
Branch: refs/heads/master
Commit: 4713f7f34fdceab9578e1f8db48de5d611660071
Parents: b646848
Author: Andreas Lehmkühler <an...@lehmi.de>
Authored: Tue Feb 6 19:08:10 2018 +0100
Committer: Andreas Lehmkühler <an...@lehmi.de>
Committed: Tue Feb 6 19:08:10 2018 +0100
----------------------------------------------------------------------
.../org/apache/pdfbox/jbig2/Dictionary.java | 6 +-
.../apache/pdfbox/jbig2/JBIG2ImageReader.java | 3 +-
.../java/org/apache/pdfbox/jbig2/Region.java | 6 +-
.../org/apache/pdfbox/jbig2/SegmentData.java | 6 +-
.../arithmetic/ArithmeticIntegerDecoder.java | 5 +-
.../org/apache/pdfbox/jbig2/image/Bitmaps.java | 70 ++++++++++++++++----
.../jbig2/segments/GenericRefinementRegion.java | 6 +-
.../pdfbox/jbig2/segments/GenericRegion.java | 31 ++++++++-
.../pdfbox/jbig2/segments/HalftoneRegion.java | 5 +-
.../org/apache/pdfbox/jbig2/util/Utils.java | 22 +++---
.../apache/pdfbox/jbig2/util/cache/Cache.java | 8 +--
11 files changed, 124 insertions(+), 44 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/pdfbox-jbig2/blob/4713f7f3/src/main/java/org/apache/pdfbox/jbig2/Dictionary.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/pdfbox/jbig2/Dictionary.java b/src/main/java/org/apache/pdfbox/jbig2/Dictionary.java
index 89fa888..3598f09 100644
--- a/src/main/java/org/apache/pdfbox/jbig2/Dictionary.java
+++ b/src/main/java/org/apache/pdfbox/jbig2/Dictionary.java
@@ -33,9 +33,9 @@ public interface Dictionary extends SegmentData {
*
* @return A list of {@link Bitmap}s as a result of the decoding process of dictionary segments.
*
- * @throws IOException
- * @throws InvalidHeaderValueException
- * @throws IntegerMaxValueException
+ * @throws IOException if an underlying IO operation fails
+ * @throws InvalidHeaderValueException if the segment header value is invalid
+ * @throws IntegerMaxValueException if the maximum value limit of an integer is exceeded
*/
public ArrayList<Bitmap> getDictionary() throws IOException, InvalidHeaderValueException, IntegerMaxValueException;
}
http://git-wip-us.apache.org/repos/asf/pdfbox-jbig2/blob/4713f7f3/src/main/java/org/apache/pdfbox/jbig2/JBIG2ImageReader.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/pdfbox/jbig2/JBIG2ImageReader.java b/src/main/java/org/apache/pdfbox/jbig2/JBIG2ImageReader.java
index db706ab..2f053b3 100644
--- a/src/main/java/org/apache/pdfbox/jbig2/JBIG2ImageReader.java
+++ b/src/main/java/org/apache/pdfbox/jbig2/JBIG2ImageReader.java
@@ -274,9 +274,10 @@ public class JBIG2ImageReader extends ImageReader {
* Simply sets the globals.
*
* @param globals - The globals to set.
- * @throws IOException
+ * @throws IOException if an error occurs
*/
public void setGlobals(JBIG2Globals globals) throws IOException {
+ // TODO remove throws IOException as there isn't any chance to trigger it
this.globals = globals;
this.document = null;
}
http://git-wip-us.apache.org/repos/asf/pdfbox-jbig2/blob/4713f7f3/src/main/java/org/apache/pdfbox/jbig2/Region.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/pdfbox/jbig2/Region.java b/src/main/java/org/apache/pdfbox/jbig2/Region.java
index dd30dcd..87f431a 100644
--- a/src/main/java/org/apache/pdfbox/jbig2/Region.java
+++ b/src/main/java/org/apache/pdfbox/jbig2/Region.java
@@ -33,9 +33,9 @@ public interface Region extends SegmentData {
*
* @return The decoded region as {@link Bitmap}.
*
- * @throws IOException
- * @throws IntegerMaxValueException
- * @throws InvalidHeaderValueException
+ * @throws IOException if an underlying IO operation fails
+ * @throws IntegerMaxValueException if the maximum value limit of an integer is exceeded
+ * @throws InvalidHeaderValueException if the segment header value is invalid
*/
public Bitmap getRegionBitmap() throws IOException, IntegerMaxValueException, InvalidHeaderValueException;
http://git-wip-us.apache.org/repos/asf/pdfbox-jbig2/blob/4713f7f3/src/main/java/org/apache/pdfbox/jbig2/SegmentData.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/pdfbox/jbig2/SegmentData.java b/src/main/java/org/apache/pdfbox/jbig2/SegmentData.java
index 8efca74..d2aaef5 100644
--- a/src/main/java/org/apache/pdfbox/jbig2/SegmentData.java
+++ b/src/main/java/org/apache/pdfbox/jbig2/SegmentData.java
@@ -34,9 +34,9 @@ public interface SegmentData {
* @param header - The segments' header (to make referred-to segments available in data part).
* @param sis - Wrapped {@code ImageInputStream} into {@code SubInputStream}.
*
- * @throws InvalidHeaderValueException
- * @throws IntegerMaxValueException
- * @throws IOException
+ * @throws InvalidHeaderValueException if the segment header value is invalid
+ * @throws IntegerMaxValueException if the maximum value limit of an integer is exceeded
+ * @throws IOException if an underlying IO operation fails
*/
public void init(SegmentHeader header, SubInputStream sis) throws InvalidHeaderValueException, IntegerMaxValueException,
IOException;
http://git-wip-us.apache.org/repos/asf/pdfbox-jbig2/blob/4713f7f3/src/main/java/org/apache/pdfbox/jbig2/decoder/arithmetic/ArithmeticIntegerDecoder.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/pdfbox/jbig2/decoder/arithmetic/ArithmeticIntegerDecoder.java b/src/main/java/org/apache/pdfbox/jbig2/decoder/arithmetic/ArithmeticIntegerDecoder.java
index 0f9fa7c..d4f1c99 100644
--- a/src/main/java/org/apache/pdfbox/jbig2/decoder/arithmetic/ArithmeticIntegerDecoder.java
+++ b/src/main/java/org/apache/pdfbox/jbig2/decoder/arithmetic/ArithmeticIntegerDecoder.java
@@ -35,8 +35,9 @@ public class ArithmeticIntegerDecoder {
/**
* Arithmetic Integer Decoding Procedure, Annex A.2.
*
+ * @param cxIAx to be decoded value
* @return Decoded value.
- * @throws IOException
+ * @throws IOException if an underlying IO operation fails
*/
public long decode(CX cxIAx) throws IOException {
int v = 0;
@@ -137,7 +138,7 @@ public class ArithmeticIntegerDecoder {
*
* @return The decoded value.
*
- * @throws IOException
+ * @throws IOException if an underlying IO operation fails
*/
public int decodeIAID(CX cxIAID, long symCodeLen) throws IOException {
// A.3 1)
http://git-wip-us.apache.org/repos/asf/pdfbox-jbig2/blob/4713f7f3/src/main/java/org/apache/pdfbox/jbig2/image/Bitmaps.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/pdfbox/jbig2/image/Bitmaps.java b/src/main/java/org/apache/pdfbox/jbig2/image/Bitmaps.java
index d73f2f8..af4a26a 100644
--- a/src/main/java/org/apache/pdfbox/jbig2/image/Bitmaps.java
+++ b/src/main/java/org/apache/pdfbox/jbig2/image/Bitmaps.java
@@ -34,20 +34,41 @@ import org.apache.pdfbox.jbig2.util.CombinationOperator;
public class Bitmaps {
- public static WritableRaster asRaster(final Bitmap bitmap) {
- return asRaster(bitmap, FilterType.Gaussian);
- }
-
- public static WritableRaster asRaster(final Bitmap bitmap, final FilterType filterType) {
- if (bitmap == null)
- throw new IllegalArgumentException("bitmap must not be null");
-
- final JBIG2ReadParam param = new JBIG2ReadParam(1, 1, 0, 0, new Rectangle(0, 0, bitmap.getWidth(),
- bitmap.getHeight()), new Dimension(bitmap.getWidth(), bitmap.getHeight()));
-
- return asRaster(bitmap, param, filterType);
- }
+ /**
+ * Returns the given bitmap as writable raster.
+ *
+ * @param bitmap the given bitmap
+ * @return the raster representation of the bitmap
+ */
+ public static WritableRaster asRaster(final Bitmap bitmap) {
+ return asRaster(bitmap, FilterType.Gaussian);
+ }
+
+ /**
+ * Returns the given bitmap as writable raster.
+ *
+ * @param bitmap the given bitmap
+ * @param filterType type of filter which is used when creating the writable raster
+ * @return the raster representation of the bitmap
+ */
+ public static WritableRaster asRaster(final Bitmap bitmap, final FilterType filterType) {
+ if (bitmap == null)
+ throw new IllegalArgumentException("bitmap must not be null");
+
+ final JBIG2ReadParam param = new JBIG2ReadParam(1, 1, 0, 0, new Rectangle(0, 0, bitmap.getWidth(),
+ bitmap.getHeight()), new Dimension(bitmap.getWidth(), bitmap.getHeight()));
+
+ return asRaster(bitmap, param, filterType);
+ }
+ /**
+ * Returns the given bitmap as writable raster.
+ *
+ * @param bitmap the given bitmap
+ * @param param ImageReadParam to be used when creating the writable raster
+ * @param filterType type of filter which is used when creating the writable raster
+ * @return the raster representation of the bitmap
+ */
public static WritableRaster asRaster(Bitmap bitmap, final ImageReadParam param, final FilterType filterType) {
if (bitmap == null)
throw new IllegalArgumentException("bitmap must not be null");
@@ -153,10 +174,23 @@ public class Bitmaps {
return dst;
}
+ /**
+ * Returns the given bitmap as buffered image.
+ *
+ * @param bitmap the given bitmap
+ * @return the image representation of the bitmap
+ */
public static BufferedImage asBufferedImage(Bitmap bitmap) {
return asBufferedImage(bitmap, FilterType.Gaussian);
}
+ /**
+ * Returns the given bitmap as buffered image.
+ *
+ * @param bitmap the given bitmap
+ * @param filterType type of filter which is used when creating the buffered image
+ * @return the image representation of the bitmap
+ */
public static BufferedImage asBufferedImage(Bitmap bitmap, FilterType filterType) {
if (bitmap == null)
throw new IllegalArgumentException("bitmap must not be null");
@@ -167,6 +201,14 @@ public class Bitmaps {
return asBufferedImage(bitmap, param, filterType);
}
+ /**
+ * Returns the given bitmap as buffered image.
+ *
+ * @param bitmap the given bitmap
+ * @param param ImageReadParam to be used when creating the buffered image
+ * @param filterType type of filter which is used when creating the buffered image
+ * @return the image representation of the bitmap
+ */
public static BufferedImage asBufferedImage(Bitmap bitmap, ImageReadParam param, FilterType filterType) {
if (bitmap == null)
throw new IllegalArgumentException("bitmap must not be null");
@@ -217,6 +259,7 @@ public class Bitmaps {
* Returns the specified rectangle area of the bitmap.
*
* @param roi - A {@link Rectangle} that specifies the requested image section.
+ * @param src the given bitmap
* @return A {@code Bitmap} that represents the requested image section.
*/
public static Bitmap extract(final Rectangle roi, final Bitmap src) {
@@ -399,6 +442,7 @@ public class Bitmaps {
* Parts of the bitmap to blit that are outside of the target bitmap will be ignored.
*
* @param src - The bitmap that should be combined with the one of the current instance.
+ * @param dst - The destination bitmap.
* @param x - The x coordinate where the upper left corner of the bitmap to blit should be
* positioned.
* @param y - The y coordinate where the upper left corner of the bitmap to blit should be
http://git-wip-us.apache.org/repos/asf/pdfbox-jbig2/blob/4713f7f3/src/main/java/org/apache/pdfbox/jbig2/segments/GenericRefinementRegion.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/pdfbox/jbig2/segments/GenericRefinementRegion.java b/src/main/java/org/apache/pdfbox/jbig2/segments/GenericRefinementRegion.java
index af59e7d..c36c736 100644
--- a/src/main/java/org/apache/pdfbox/jbig2/segments/GenericRefinementRegion.java
+++ b/src/main/java/org/apache/pdfbox/jbig2/segments/GenericRefinementRegion.java
@@ -173,9 +173,9 @@ public class GenericRefinementRegion implements Region {
/**
* Decode using a template and arithmetic coding, as described in 6.3.5.6
*
- * @throws IOException
- * @throws InvalidHeaderValueException
- * @throws IntegerMaxValueException
+ * @throws IOException if an underlying IO operation fails
+ * @throws InvalidHeaderValueException if a segment header value is invalid
+ * @throws IntegerMaxValueException if the maximum value limit of an integer is exceeded
*/
public Bitmap getRegionBitmap() throws IOException, IntegerMaxValueException, InvalidHeaderValueException {
if (null == regionBitmap) {
http://git-wip-us.apache.org/repos/asf/pdfbox-jbig2/blob/4713f7f3/src/main/java/org/apache/pdfbox/jbig2/segments/GenericRegion.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/pdfbox/jbig2/segments/GenericRegion.java b/src/main/java/org/apache/pdfbox/jbig2/segments/GenericRegion.java
index 9c42f04..a799f73 100644
--- a/src/main/java/org/apache/pdfbox/jbig2/segments/GenericRegion.java
+++ b/src/main/java/org/apache/pdfbox/jbig2/segments/GenericRegion.java
@@ -152,7 +152,7 @@ public class GenericRegion implements Region {
/**
* The procedure is described in 6.2.5.7, page 17.
*
- * @returns The decoded {@link Bitmap} of this region.
+ * @return The decoded {@link Bitmap} of this region.
*/
public Bitmap getRegionBitmap() throws IOException {
if (null == regionBitmap) {
@@ -807,6 +807,12 @@ public class GenericRegion implements Region {
/**
* Used by {@link SymbolDictionary}.
+ *
+ * @param isMMREncoded the data is MMR encoded
+ * @param dataOffset the offset
+ * @param dataLength the length of the data
+ * @param gbh bitmap height
+ * @param gbw bitmap width
*/
protected void setParameters(final boolean isMMREncoded, final long dataOffset, final long dataLength, final int gbh,
final int gbw) {
@@ -821,6 +827,17 @@ public class GenericRegion implements Region {
}
/**
+ * @param isMMREncoded the data is MMR encoded
+ * @param sdTemplate sd template
+ * @param isTPGDon is TPGDon
+ * @param useSkip use skip
+ * @param sdATX x values gbA pixels
+ * @param sdATY y values gbA pixels
+ * @param symWidth bitmap width
+ * @param hcHeight bitmap height
+ * @param cx context for the arithmetic decoder
+ * @param arithmeticDecoder the arithmetic decode to be used
+ *
* Used by {@link SymbolDictionary}.
*/
protected void setParameters(final boolean isMMREncoded, final byte sdTemplate, final boolean isTPGDon,
@@ -844,6 +861,18 @@ public class GenericRegion implements Region {
/**
* Used by {@link PatternDictionary} and {@link HalftoneRegion}.
+ *
+ * @param isMMREncoded the data is MMR encoded
+ * @param dataOffset the offset
+ * @param dataLength the length of the data
+ * @param gbh bitmap height
+ * @param gbw bitmap width
+ * @param gbTemplate gb template
+ * @param isTPGDon is TPGDon
+ * @param useSkip use skip
+ * @param gbAtX x values of gbA pixels
+ * @param gbAtY y values of gbA pixels
+ *
*/
protected void setParameters(final boolean isMMREncoded, final long dataOffset, final long dataLength, final int gbh,
final int gbw, final byte gbTemplate, final boolean isTPGDon, final boolean useSkip, final short[] gbAtX,
http://git-wip-us.apache.org/repos/asf/pdfbox-jbig2/blob/4713f7f3/src/main/java/org/apache/pdfbox/jbig2/segments/HalftoneRegion.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/pdfbox/jbig2/segments/HalftoneRegion.java b/src/main/java/org/apache/pdfbox/jbig2/segments/HalftoneRegion.java
index 384f09f..4121d58 100644
--- a/src/main/java/org/apache/pdfbox/jbig2/segments/HalftoneRegion.java
+++ b/src/main/java/org/apache/pdfbox/jbig2/segments/HalftoneRegion.java
@@ -153,7 +153,10 @@ public class HalftoneRegion implements Region {
/**
* The procedure is described in JBIG2 ISO standard, 6.6.5.
*
- * @returns The decoded {@link Bitmap} of this region.
+ * @return The decoded {@link Bitmap} of this region.
+ *
+ * @throws IOException if an underlying IO operation fails
+ * @throws InvalidHeaderValueException if a segment header value is invalid
*/
public Bitmap getRegionBitmap() throws IOException, InvalidHeaderValueException {
if (null == halftoneRegionBitmap) {
http://git-wip-us.apache.org/repos/asf/pdfbox-jbig2/blob/4713f7f3/src/main/java/org/apache/pdfbox/jbig2/util/Utils.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/pdfbox/jbig2/util/Utils.java b/src/main/java/org/apache/pdfbox/jbig2/util/Utils.java
index ae2ae7a..daeb3b3 100644
--- a/src/main/java/org/apache/pdfbox/jbig2/util/Utils.java
+++ b/src/main/java/org/apache/pdfbox/jbig2/util/Utils.java
@@ -29,8 +29,8 @@ public class Utils {
* <code>enlargeToGrid(r).contains(r) == true</code> holds. This can be depicted as the edges
* being stretched in an outward direction.
*
- * @param r
- * @return
+ * @param r the given rectangle
+ * @return the resulting rectangle
*/
public static Rectangle enlargeRectToGrid(Rectangle2D r) {
final int x0 = floor(r.getMinX());
@@ -44,8 +44,10 @@ public class Utils {
* Return a new rectangle which covers the area of the given rectangle with an additional margin
* on the sides.
*
- * @param r
- * @param marginX
+ * @param r the given rectangle
+ * @param marginX horizontal value of the additional margin
+ * @param marginY vertical value of the additional margin
+ * @return the resulting rectangle
*/
public static Rectangle2D dilateRect(Rectangle2D r, double marginX, double marginY) {
return new Rectangle2D.Double(r.getX() - marginX, r.getY() - marginY, r.getWidth() + 2 * marginX, r.getHeight() + 2
@@ -55,9 +57,9 @@ public class Utils {
/**
* Clamp the value into the range [min..max].
*
- * @param value
- * @param min
- * @param max
+ * @param value input value
+ * @param min minimal value
+ * @param max maximal value
* @return the clamped value
*/
public static double clamp(double value, double min, double max) {
@@ -72,7 +74,7 @@ public class Utils {
* A fast implementation of {@link Math#floor(double)}.
*
* @param x the argument
- * @return
+ * @return resulting floor value
*/
public static int floor(double x) {
return (int) (x + BIG_ENOUGH_FLOOR) - BIG_ENOUGH_INT;
@@ -82,7 +84,7 @@ public class Utils {
* A fast implementation of {@link Math#round(double)}.
*
* @param x the argument
- * @return
+ * @return rounded value
*/
public static int round(double x) {
return (int) (x + BIG_ENOUGH_ROUND) - BIG_ENOUGH_INT;
@@ -92,7 +94,7 @@ public class Utils {
* A fast implementation of {@link Math#ceil(double)}.
*
* @param x the argument
- * @return
+ * @return resulting ceil value
*/
public static int ceil(double x) {
return BIG_ENOUGH_INT - (int) (BIG_ENOUGH_FLOOR - x);
http://git-wip-us.apache.org/repos/asf/pdfbox-jbig2/blob/4713f7f3/src/main/java/org/apache/pdfbox/jbig2/util/cache/Cache.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/pdfbox/jbig2/util/cache/Cache.java b/src/main/java/org/apache/pdfbox/jbig2/util/cache/Cache.java
index 41038cf..6454784 100644
--- a/src/main/java/org/apache/pdfbox/jbig2/util/cache/Cache.java
+++ b/src/main/java/org/apache/pdfbox/jbig2/util/cache/Cache.java
@@ -21,9 +21,9 @@ public interface Cache {
/**
*
- * @param key
- * @param value
- * @param sizeEstimate
+ * @param key value to be used as key
+ * @param value value to be stored
+ * @param sizeEstimate estimated size
*
* @return the old object, that was replaced if present. Otherwise {@code null}.
*/
@@ -40,7 +40,7 @@ public interface Cache {
/**
*
- * @param key
+ * @param key the key of the to be removed object
* @return the removed object, if present. Otherwise {@code null}.
*/
Object remove(Object key);