WIP fix Javadocs warnings

kinow · kinow · commit 273d293c3f71 · 2022-11-11T23:52:44.000+01:00
diff --git a/src/main/java/org/apache/commons/imaging/color/ColorConversions.java b/src/main/java/org/apache/commons/imaging/color/ColorConversions.java
@@ -19,20 +19,15 @@
 
 public final class ColorConversions {
 
+    /*
+     * These constants are for CIEXYZ to CIELAB conversion.
+     * For reference: <a href="https://en.wikipedia.org/wiki/CIELAB_color_space#From_CIEXYZ_to_CIELAB">From CIEXYZ to CIELAB, from CIELAB color space<a/>
+     */
     // White reference
-    /** see: https://en.wikipedia.org/wiki/CIELAB_color_space#From_CIEXYZ_to_CIELAB[10] */
     private static final double REF_X = 95.047; // Observer= 2°, Illuminant= D65
-
-    /** see: https://en.wikipedia.org/wiki/CIELAB_color_space#From_CIEXYZ_to_CIELAB[10] */
     private static final double REF_Y = 100.000;
-
-    /** see: https://en.wikipedia.org/wiki/CIELAB_color_space#From_CIEXYZ_to_CIELAB[10] */
     private static final double REF_Z = 108.883;
-
-    /** see: https://en.wikipedia.org/wiki/CIELAB_color_space#From_CIEXYZ_to_CIELAB[10] */
     private static final double XYZ_m = 7.787037; // match in slope. Note commonly seen 7.787 gives worse results
-
-    /** see: https://en.wikipedia.org/wiki/CIELAB_color_space#From_CIEXYZ_to_CIELAB[10] */
     private static final double XYZ_t0 = 0.008856;
 
     private ColorConversions() {
diff --git a/src/main/java/org/apache/commons/imaging/formats/jpeg/decoder/Dct.java b/src/main/java/org/apache/commons/imaging/formats/jpeg/decoder/Dct.java
@@ -252,9 +252,10 @@ public static void forwardDCT8x8(final float[] matrix) {
 
     /**
      * Fast inverse Dct using AA&N. This is taken from the beautiful
-     * http://vsr.finermatik.tu-chemnitz.de/~jan/MPEG/HTML/IDCT.html which gives
-     * easy equations and properly explains constants and scaling factors. Terms
-     * have been inlined and the negation optimized out of existence.
+     * <a href="http://vsr.finermatik.tu-chemnitz.de/~jan/MPEG/HTML/IDCT.html">(broken link)</a>
+     * which gives easy equations and properly explains constants and
+     * scaling factors. Terms have been inlined and the negation
+     * optimized out of existence.
      */
     public static void inverseDCT8(final float[] vector) {
         // B1
diff --git a/src/main/java/org/apache/commons/imaging/formats/jpeg/segments/App14Segment.java b/src/main/java/org/apache/commons/imaging/formats/jpeg/segments/App14Segment.java
@@ -24,7 +24,7 @@
 import java.nio.charset.StandardCharsets;
 
 /**
- * http://www.aiim.org/documents/standards/PDF-Ref/References/Adobe/5116.DCT_Filter.pdf
+ * @see <a href="https://web.archive.org/web/20220122061015/http://www.lprng.com/RESOURCES/ADOBE/5116.DCT_Filter.pdf">Supporting the DCT Filters in PostScript Level 2</a>
  */
 public class App14Segment extends AppnSegment {
     private static final byte[] ADOBE_PREFIX;
diff --git a/src/main/java/org/apache/commons/imaging/formats/tiff/TiffReader.java b/src/main/java/org/apache/commons/imaging/formats/tiff/TiffReader.java
@@ -440,7 +440,7 @@ private TiffImageData getTiffRawImageData(final ByteSource byteSource,
                 rowsPerStrip = rowsPerStripField.getIntValue();
             } else {
                 final TiffField imageHeight = directory.findField(TiffTagConstants.TIFF_TAG_IMAGE_LENGTH);
-                /**
+                /*
                  * if rows per strip not present then rowsPerStrip is equal to
                  * imageLength or an infinity value;
                  */
diff --git a/src/main/java/org/apache/commons/imaging/formats/tiff/constants/AdobePageMaker6TagConstants.java b/src/main/java/org/apache/commons/imaging/formats/tiff/constants/AdobePageMaker6TagConstants.java
@@ -28,47 +28,88 @@
 import org.apache.commons.imaging.formats.tiff.taginfos.TagInfoShort;
 
 /**
- * TIFF specification supplement 1
- * <BR>
- * Enhancements for Adobe PageMaker(R) 6.0 software
- * <BR>
- * http://partners.adobe.com/public/developer/en/tiff/TIFFPM6.pdf
+ * TIFF specification supplement 1.
+ *
+ * @see <a href="https://web.archive.org/web/20180810205521/https://www.adobe.io/content/udp/en/open/standards/TIFF/_jcr_content/contentbody/download_1704706507/file.res/TIFFPM6.pdf">Adobe PageMaker(R) 6.0 TIFF Technical Notes</a>
  */
 public final class AdobePageMaker6TagConstants {
 
+    /**
+     * SubIFDs.
+     *
+     * <p>Each value is an offset (from the beginning of the TIFF file, as always) to a child
+     * IFD. Child images provide extra information for the parent image—such as a
+     * sub-sampled version of the parent image.</p>
+     */
     public static final TagInfoLongOrIFD TIFF_TAG_SUB_IFD = new TagInfoLongOrIFD(
             "SubIFDs",  0x014a, -1,
             TiffDirectoryType.EXIF_DIRECTORY_UNKNOWN, true);
-
+    /**
+     * ClipPath.
+     *
+     * <p>A TIFF ClipPath is intended to mirror the essentials of PostScript's path creation
+     * functionality, so that the operators listed below can be easily translated into
+     * PostScript, and, conversely, any PostScript path can be represented as a TIFF
+     * ClipPath.</p>
+     */
     public static final TagInfoBytes TIFF_TAG_CLIP_PATH = new TagInfoBytes(
             "ClipPath",  0x0157, -1,
             TiffDirectoryType.EXIF_DIRECTORY_UNKNOWN);
 
+    /**
+     * XClipPathUnits.
+     *
+     * <p>The number of units that span the width of the image, in terms of integer ClipPath
+     * coordinates.</p>
+     */
     public static final TagInfoLong TIFF_TAG_XCLIP_PATH_UNITS = new TagInfoLong(
             "XClipPathUnits", 0x0158,
             TiffDirectoryType.EXIF_DIRECTORY_UNKNOWN);
 
+    /**
+     * YClipPathUnits.
+     *
+     * <p>The number of units that span the height of the image, in terms of integer ClipPath
+     * coordinates.</p>
+     */
     public static final TagInfoLong TIFF_TAG_YCLIP_PATH_UNITS = new TagInfoLong(
             "YClipPathUnits", 0x0159,
             TiffDirectoryType.EXIF_DIRECTORY_UNKNOWN);
 
+    /**
+     * Indexed.
+     *
+     * <p>Indexed images are images where the "pixels" do not represent color values, but
+     * rather an index (usually 8-bit) into a separate color table, the ColorMap.
+     * ColorMap is required for an Indexed image.</p>
+     */
     public static final TagInfoShort TIFF_TAG_INDEXED = new TagInfoShort(
             "Indexed", 0x015a,
             TiffDirectoryType.EXIF_DIRECTORY_UNKNOWN);
 
-    public static final int INDEXED_VALUE_NOT_INDEXED = 0;
-    public static final int INDEXED_VALUE_INDEXED = 1;
-
+    /**
+     * OPIProxy.
+     *
+     * <p>OPIProxy gives information concerning whether this image is a low-resolution
+     * proxy of a high-resolution image.</p>
+     */
     public static final TagInfoShort TIFF_TAG_OPIPROXY = new TagInfoShort(
             "OPIProxy", 0x015f,
             TiffDirectoryType.EXIF_DIRECTORY_UNKNOWN);
-    public static final int OPIPROXY_VALUE_HIGHER_RESOLUTION_IMAGE_DOES_NOT_EXIST = 0;
-    public static final int OPIPROXY_VALUE_HIGHER_RESOLUTION_IMAGE_EXISTS = 1;
 
+    /**
+     * ImageID.
+     *
+     * <p>ImageID is the full pathname of the original, high-resolution image, or any other
+     * identifying string that uniquely identifies the original image.</p>
+     */
     public static final TagInfoAscii TIFF_TAG_IMAGE_ID = new TagInfoAscii(
             "ImageID", 0x800d, -1,
             TiffDirectoryType.EXIF_DIRECTORY_UNKNOWN);
 
+    /**
+     * A list with all the Adobe PageMaker 6 tags.
+     */
     public static final List<TagInfo> ALL_ADOBE_PAGEMAKER_6_TAGS =
             Collections.unmodifiableList(Arrays.asList(
                     TIFF_TAG_SUB_IFD,
diff --git a/src/main/java/org/apache/commons/imaging/formats/tiff/constants/AdobePhotoshopTagConstants.java b/src/main/java/org/apache/commons/imaging/formats/tiff/constants/AdobePhotoshopTagConstants.java
@@ -24,22 +24,34 @@
 import org.apache.commons.imaging.formats.tiff.taginfos.TagInfoUndefineds;
 
 /**
- * TIFF specification supplement 2
- * <BR>
- * Adobe Photoshop (R) TIFF Technical Notes
- * <BR>
- * http://partners.adobe.com/public/developer/en/tiff/TIFFphotoshop.pdf
+ * TIFF specification supplement 2.
+ *
+ * See <a href="https://web.archive.org/web/20180810205806/https://www.adobe.io/content/udp/en/open/standards/TIFF/_jcr_content/contentbody/download_1370394226/file.res/TIFFphotoshop.pdf">Adobe Photoshop (R) TIFF Technical Notes</a>
  */
 public final class AdobePhotoshopTagConstants {
 
+    /**
+     * JPEGTables.
+     *
+     * <p>JPEGTables provides default JPEG quantization and/or Huffman tables which are used whenever
+     * a segment data stream does not contain its own tables, as specified below.</p>
+     */
     public static final TagInfoUndefineds EXIF_TAG_JPEGTABLES = new TagInfoUndefineds(
             "JPEGTables", 0x015b, -1,
             TiffDirectoryType.EXIF_DIRECTORY_UNKNOWN);
 
+    /**
+     * ImageSourceData.
+     *
+     * <p>Image source data bytes.</p>
+     */
     public static final TagInfoUndefineds EXIF_TAG_IMAGE_SOURCE_DATA = new TagInfoUndefineds(
             "ImageSourceData", 0x935c, -1,
             TiffDirectoryType.EXIF_DIRECTORY_IFD0);
 
+    /**
+     * A list with all the Adobe Photoshop tags.
+     */
     public static final List<TagInfo> ALL_ADOBE_PHOTOSHOP_TAGS =
             Collections.unmodifiableList(Arrays.<TagInfo> asList(
                     EXIF_TAG_JPEGTABLES,
diff --git a/src/main/java/org/apache/commons/imaging/formats/tiff/constants/AliasSketchbookProTagConstants.java b/src/main/java/org/apache/commons/imaging/formats/tiff/constants/AliasSketchbookProTagConstants.java
@@ -24,19 +24,23 @@
 import org.apache.commons.imaging.formats.tiff.taginfos.TagInfoAscii;
 
 /**
- * Alias Sketchbook Pro multi-layer TIFF
- * <BR>
- * http://www.awaresystems.be/imaging/tiff/tifftags/docs/alias.html
+ * Alias Sketchbook Pro multi-layer TIFF.
+ *
+ * @see <a href="https://web.archive.org/web/20180905213310/https://awaresystems.be/imaging/tiff/tifftags/docs/alias.html">Alias Sketchbook Pro Multi-Layer TIFF File Format Specification</a>
  */
 public final class AliasSketchbookProTagConstants {
 
+    /**
+     * Identifies a file as an Alias Multi Layer TIFF file.
+     */
     public static final TagInfoAscii EXIF_TAG_ALIAS_LAYER_METADATA = new TagInfoAscii(
             "Alias Layer Metadata", 0xc660, -1,
             TiffDirectoryType.EXIF_DIRECTORY_UNKNOWN);
 
-    public static final List<TagInfo> ALL_ALIAS_SKETCHBOOK_PRO_TAGS =
-            Collections.unmodifiableList(Arrays.<TagInfo> asList(
-                    EXIF_TAG_ALIAS_LAYER_METADATA));
+    /**
+     * A list with all the Alias Sketchbook Pro multi-layer tags.
+     */
+    public static final List<TagInfo> ALL_ALIAS_SKETCHBOOK_PRO_TAGS = Collections.singletonList(EXIF_TAG_ALIAS_LAYER_METADATA);
 
     private AliasSketchbookProTagConstants() {
     }
diff --git a/src/main/java/org/apache/commons/imaging/formats/tiff/constants/DcfTagConstants.java b/src/main/java/org/apache/commons/imaging/formats/tiff/constants/DcfTagConstants.java
@@ -26,9 +26,9 @@
 import org.apache.commons.imaging.formats.tiff.taginfos.TagInfoShortOrLong;
 
 /**
- * Design rule for Camera Filesystem
- * <BR>
- * http://www.exif.org/dcf.PDF
+ * Design rule for Camera Filesystem.
+ *
+ * @see <a href="https://web.archive.org/web/20220121012334/http://www.exif.org/dcf.PDF">Design rule for Camera File system Version 1.0</a>
  */
 public final class DcfTagConstants {
 
diff --git a/src/main/java/org/apache/commons/imaging/formats/tiff/constants/Rfc2301TagConstants.java b/src/main/java/org/apache/commons/imaging/formats/tiff/constants/Rfc2301TagConstants.java
@@ -33,12 +33,11 @@
 
 /**
  * RFC 2301: File Format for Internet Fax
- * <BR>
- * www.ietf.org/rfc/rfc2301.txt
- * <BR>
- * Also subsumes  "The spirit of TIFF class F"
- * <BR>
- * http://cool.conservation-us.org/bytopic/imaging/std/tiff-f.html
+ *
+ * <p>Also subsumes  "The spirit of TIFF class F"</p>
+ *
+ * @see <a href="www.ietf.org/rfc/rfc2301.txt">RFC-2301 File Format for Internet Fax</a>
+ * @see <a href="https://web.archive.org/web/20191223140908/http://cool.conservation-us.org/bytopic/imaging/std/tiff-f.html">TIFF-F Revised Specification</a>
  */
 public final class Rfc2301TagConstants {
 
diff --git a/src/main/java/org/apache/commons/imaging/formats/tiff/constants/Tiff4TagConstants.java b/src/main/java/org/apache/commons/imaging/formats/tiff/constants/Tiff4TagConstants.java
@@ -25,8 +25,8 @@
 
 /**
  * Tags in TIFF4 but NOT in TIFF6.
- * <BR>
- * http://cool.conservation-us.org/bytopic/imaging/std/tiff4.html
+ *
+ * @see <a href="https://web.archive.org/web/20220516025327/https://cool.culturalheritage.org/bytopic/imaging/std/tiff4.html">Tag Image File Format Rev 4.0</a>
  */
 public final class Tiff4TagConstants {
 
diff --git a/src/main/java/org/apache/commons/imaging/formats/tiff/constants/TiffTagConstants.java b/src/main/java/org/apache/commons/imaging/formats/tiff/constants/TiffTagConstants.java
@@ -36,8 +36,8 @@
 
 /**
  * Tags from the TIFF6 specification.
- * <BR>
- * http://partners.adobe.com/public/developer/en/tiff/TIFF6.pdf
+ *
+ * @see <a href="https://web.archive.org/web/20090126205823/http://partners.adobe.com/public/developer/en/tiff/TIFF6.pdf">TIFF Revision 6.0</a>
  */
 public final class TiffTagConstants {
 
diff --git a/src/main/java/org/apache/commons/imaging/formats/tiff/datareaders/BitInputStream.java b/src/main/java/org/apache/commons/imaging/formats/tiff/datareaders/BitInputStream.java
@@ -89,10 +89,10 @@ public final int readBits(final int count) throws IOException {
             return is.read();
         }
 
-        /**
+        /*
          * Taking default order of the Tiff to be Little Endian and reversing
          * the bytes in the end if its Big Endian.This is done because majority
-         * (may be all) of the files will be of Little Endian.
+         * (maybe all) of the files will be of Little Endian.
          */
         if (byteOrder == ByteOrder.BIG_ENDIAN) {
             switch (count) {
diff --git a/src/main/java/org/apache/commons/imaging/formats/tiff/datareaders/ImageDataReader.java b/src/main/java/org/apache/commons/imaging/formats/tiff/datareaders/ImageDataReader.java
@@ -244,8 +244,8 @@ protected boolean isHomogenous(final int size) {
      *
      * @param bis the stream to read from
      * @param result the samples array to populate, must be the same length as
-     * bitsPerSample.length
-     * @throws IOException
+     * {@code bitsPerSample.length}
+     * @throws IOException if it fails to read bits from the stream
      */
     void getSamplesAsBytes(final BitInputStream bis, final int[] result) throws IOException {
         for (int i = 0; i < bitsPerSample.length; i++) {
