Merge pull request #65 from image-rs/error-type

Improve the error types

src/error.rs

@@ -11,19 +11,26 @@ use ColorType;
 /// Tiff error kinds.
 #[derive(Debug)]
 pub enum TiffError {
-    /// The Image is not formatted properly
+    /// The Image is not formatted properly.
     FormatError(TiffFormatError),
 
-    /// The Decoder does not support this image format
+    /// The Decoder does not support features required by the image.
     UnsupportedError(TiffUnsupportedError),
 
-    /// An I/O Error occurred while decoding the image
+    /// An I/O Error occurred while decoding the image.
     IoError(io::Error),
 
-    /// The Limits of the Decoder is exceeded,
+    /// The Limits of the Decoder is exceeded.
     LimitsExceeded,
 }
 
+/// The image is not formatted properly.
+///
+/// This indicates that the encoder producing the image might behave incorrectly or that the input
+/// file has been corrupted.
+///
+/// The list of variants may grow to incorporate errors of future features. Matching against this
+/// exhaustively is not covered by interface stability guarantees.
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub enum TiffFormatError {
     TiffSignatureNotFound,
@@ -36,6 +43,9 @@ pub enum TiffFormatError {
     UnsignedIntegerExpected(Value),
     SignedIntegerExpected(Value),
     InflateError(InflateError),
+    #[doc(hidden)]
+    /// Do not match against this variant. It may get removed.
+    __NonExhaustive,
 }
 
 impl fmt::Display for TiffFormatError {
@@ -58,17 +68,19 @@ impl fmt::Display for TiffFormatError {
                 write!(fmt, "Expected signed integer, {:?} found.", val)
             }
             InflateError(_) => write!(fmt, "Failed to decode inflate data."),
+            __NonExhaustive => unreachable!(),
         }
     }
 }
 
+/// Decompression failed due to faulty compressed data.
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct InflateError {
     status: TINFLStatus,
 }
 
 impl InflateError {
-    pub fn new(status: TINFLStatus) -> Self {
+    pub(crate) fn new(status: TINFLStatus) -> Self {
         Self { status }
     }
 }
@@ -79,6 +91,14 @@ impl TiffError {
     }
 }
 
+/// The Decoder does not support features required by the image.
+///
+/// This only captures known failures for which the standard either does not require support or an
+/// implementation has been planned but not yet completed. Some variants may become unused over
+/// time and will then get deprecated before being removed.
+///
+/// The list of variants may grow. Matching against this exhaustively is not covered by interface
+/// stability guarantees.
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub enum TiffUnsupportedError {
     HorizontalPredictor(ColorType),
@@ -91,6 +111,9 @@ pub enum TiffUnsupportedError {
     UnsupportedBitsPerChannel(u8),
     UnsupportedPlanarConfig(Option<PlanarConfiguration>),
     UnsupportedDataType,
+    #[doc(hidden)]
+    /// Do not match against this variant. It may get removed.
+    __NonExhaustive,
 }
 
 impl fmt::Display for TiffUnsupportedError {
@@ -128,6 +151,7 @@ impl fmt::Display for TiffUnsupportedError {
                 write!(fmt, "Unsupported planar configuration “{:?}”.", config)
             }
             UnsupportedDataType => write!(fmt, "Unsupported data type."),
+            __NonExhaustive => unreachable!(),
         }
     }
 }

src/lib.rs

@@ -14,7 +14,7 @@ pub mod decoder;
 pub mod encoder;
 mod error;
 
-pub use self::error::{TiffError, TiffFormatError, TiffResult, TiffUnsupportedError};
+pub use self::error::{InflateError, TiffError, TiffFormatError, TiffResult, TiffUnsupportedError};
 
 /// An enumeration over supported color types and their bit depths
 #[derive(Copy, PartialEq, Eq, Debug, Clone, Hash)]