From 1d9944c5c506d0b7af182bcf6eda23c223bcfa09 Mon Sep 17 00:00:00 2001
From: Andreas Molzer <andreas.molzer@gmx.de>
Date: Wed, 20 Nov 2019 20:58:45 +0100
Subject: [PATCH] Mark both detailed error types as non-exhaustive

This makes it cheaper to introduce new features that might require
amending the list of variants by allowing us to introduce previously
uncovered causes or more specialized representations.
---
 src/error.rs | 32 ++++++++++++++++++++++++++++----
 1 file changed, 28 insertions(+), 4 deletions(-)

diff --git a/src/error.rs b/src/error.rs
index 95b3435..8705149 100644
--- a/src/error.rs
+++ b/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.
+///
+/// The indicate 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,10 +68,12 @@ 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,
@@ -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!(),
         }
     }
 }