WIP fix Javadocs warnings

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() {

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

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;

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;
                  */

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,

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,

src/main/java/org/apache/commons/imaging/formats/tiff/constants/AliasSketchbookProTagConstants.java

@@ -16,27 +16,30 @@
  */
 package org.apache.commons.imaging.formats.tiff.constants;
 
-import java.util.Arrays;
 import java.util.Collections;
 import java.util.List;
 
 import org.apache.commons.imaging.formats.tiff.taginfos.TagInfo;
 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() {
     }

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 {
 

src/main/java/org/apache/commons/imaging/formats/tiff/constants/DngTagConstants.java

@@ -42,7 +42,7 @@
 /**
  * Digital Negative (DNG) Specification
  * <BR>
- * http://www.adobe.com/products/dng/pdfs/dng_spec_1_3_0_0.pdf
+ * <a href="http://www.adobe.com/products/dng/pdfs/dng_spec_1_3_0_0.pdf">...</a>
  */
 public final class DngTagConstants {
 

src/main/java/org/apache/commons/imaging/formats/tiff/constants/ExifTagConstants.java

@@ -42,11 +42,11 @@
 
 /**
  * References:
- * http://www.sno.phy.queensu.ca/~phil/exiftool/TagNames/EXIF.html
- * http://tiki-lounge.com/~raf/tiff/fields.html
- * http://www.awaresystems.be/imaging/tiff/tifftags.html
+ * <a href="http://www.sno.phy.queensu.ca/~phil/exiftool/TagNames/EXIF.html">...</a>
+ * <a href="http://tiki-lounge.com/~raf/tiff/fields.html">...</a>
+ * <a href="http://www.awaresystems.be/imaging/tiff/tifftags.html">...</a>
  *
- * "Stonits": http://www.anyhere.com/gward/pixformat/tiffluv.html
+ * "Stonits": <a href="http://www.anyhere.com/gward/pixformat/tiffluv.html">...</a>
  */
 public final class ExifTagConstants {
 

src/main/java/org/apache/commons/imaging/formats/tiff/constants/GdalLibraryTagConstants.java

@@ -26,9 +26,9 @@
 /**
  * GDAL library.
  * <BR>
- * http://www.awaresystems.be/imaging/tiff/tifftags/gdal_metadata.html
+ * <a href="http://www.awaresystems.be/imaging/tiff/tifftags/gdal_metadata.html">...</a>
  * <BR>
- * http://www.awaresystems.be/imaging/tiff/tifftags/gdal_nodata.html
+ * <a href="http://www.awaresystems.be/imaging/tiff/tifftags/gdal_nodata.html">...</a>
  */
 public final class GdalLibraryTagConstants {
 

src/main/java/org/apache/commons/imaging/formats/tiff/constants/GeoTiffTagConstants.java

@@ -28,7 +28,7 @@
 /**
  * Geo Tiff.
  * <BR>
- * http://www.remotesensing.org/geotiff/spec/contents.html
+ * <a href="http://www.remotesensing.org/geotiff/spec/contents.html">...</a>
  */
 public final class GeoTiffTagConstants {
 

src/main/java/org/apache/commons/imaging/formats/tiff/constants/MolecularDynamicsGelTagConstants.java

@@ -29,7 +29,7 @@
 /**
  * Molecular Dynamics GEL file format
  * <BR>
- * http://www.awaresystems.be/imaging/tiff/tifftags/docs/gel.html
+ * <a href="http://www.awaresystems.be/imaging/tiff/tifftags/docs/gel.html">...</a>
  */
 public final class MolecularDynamicsGelTagConstants {
 

src/main/java/org/apache/commons/imaging/formats/tiff/constants/OceScanjobTagConstants.java

@@ -26,7 +26,7 @@
 /**
  * Oce Scanjob.
  * <BR>
- * http://www.awaresystems.be/imaging/tiff/tifftags/docs/oce.html
+ * <a href="http://www.awaresystems.be/imaging/tiff/tifftags/docs/oce.html">...</a>
  */
 public final class OceScanjobTagConstants {
 

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 {
 

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 {
 

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 {
 

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) {

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++) {