From 6bcc17a02034926065c3e7145dd241748d29c837 Mon Sep 17 00:00:00 2001
From: Harald Kuhr <harald.kuhr@gmail.com>
Date: Wed, 18 May 2022 20:31:28 +0200
Subject: [PATCH] Documentation & details.

(cherry picked from commit 8992406f502a1c8415ac9ed80267d8a705541440)
---
 .../contrib/exif/EXIFUtilities.java           | 28 ++++++++++++++++---
 1 file changed, 24 insertions(+), 4 deletions(-)

diff --git a/contrib/src/main/java/com/twelvemonkeys/contrib/exif/EXIFUtilities.java b/contrib/src/main/java/com/twelvemonkeys/contrib/exif/EXIFUtilities.java
index 5a23a43b..b50b1659 100644
--- a/contrib/src/main/java/com/twelvemonkeys/contrib/exif/EXIFUtilities.java
+++ b/contrib/src/main/java/com/twelvemonkeys/contrib/exif/EXIFUtilities.java
@@ -30,9 +30,14 @@ import static com.twelvemonkeys.contrib.tiff.TIFFUtilities.applyOrientation;
 public class EXIFUtilities {
     /**
      * Reads image and metadata, applies Exif orientation to image, and returns everything as an {@code IIOImage}.
+     * The returned {@code IIOImage} will always contain an image and no raster, and
+     * the {@code RenderedImage} may be safely cast to a {@code BufferedImage}.
+     *
+     * If no registered {@code ImageReader} claims to be able to read the input, {@code null} is returned.
      *
      * @param input a {@code URL}
-     * @return an {@code IIOImage} containing the correctly oriented image and metadata including rotation info.
+     * @return an {@code IIOImage} containing the correctly oriented image and metadata including rotation info, or
+     * {@code null}.
      * @throws IOException if an error occurs during reading.
      */
     public static IIOImage readWithOrientation(final URL input) throws IOException {
@@ -43,9 +48,14 @@ public class EXIFUtilities {
 
     /**
      * Reads image and metadata, applies Exif orientation to image, and returns everything as an {@code IIOImage}.
+     * The returned {@code IIOImage} will always contain an image and no raster, and
+     * the {@code RenderedImage} may be safely cast to a {@code BufferedImage}.
+     *
+     * If no registered {@code ImageReader} claims to be able to read the input, {@code null} is returned.
      *
      * @param input an {@code InputStream}
-     * @return an {@code IIOImage} containing the correctly oriented image and metadata including rotation info.
+     * @return an {@code IIOImage} containing the correctly oriented image and metadata including rotation info, or
+     * {@code null}.
      * @throws IOException if an error occurs during reading.
      */
     public static IIOImage readWithOrientation(final InputStream input) throws IOException {
@@ -56,9 +66,14 @@ public class EXIFUtilities {
 
     /**
      * Reads image and metadata, applies Exif orientation to image, and returns everything as an {@code IIOImage}.
+     * The returned {@code IIOImage} will always contain an image and no raster, and
+     * the {@code RenderedImage} may be safely cast to a {@code BufferedImage}.
+     *
+     * If no registered {@code ImageReader} claims to be able to read the input, {@code null} is returned.
      *
      * @param input a {@code File}
-     * @return an {@code IIOImage} containing the correctly oriented image and metadata including rotation info.
+     * @return an {@code IIOImage} containing the correctly oriented image and metadata including rotation info or
+     * {@code null}.
      * @throws IOException if an error occurs during reading.
      */
     public static IIOImage readWithOrientation(final File input) throws IOException {
@@ -69,9 +84,14 @@ public class EXIFUtilities {
 
     /**
      * Reads image and metadata, applies Exif orientation to image, and returns everything as an {@code IIOImage}.
+     * The returned {@code IIOImage} will always contain an image and no raster, and
+     * the {@code RenderedImage} may be safely cast to a {@code BufferedImage}.
+     *
+     * If no registered {@code ImageReader} claims to be able to read the input, {@code null} is returned.
      *
      * @param input an {@code ImageInputStream}
-     * @return an {@code IIOImage} containing the correctly oriented image and metadata including rotation info.
+     * @return an {@code IIOImage} containing the correctly oriented image and metadata including rotation info, or
+     * {@code null}.
      * @throws IOException if an error occurs during reading.
      */
     public static IIOImage readWithOrientation(final ImageInputStream input) throws IOException {