From cbdb9fdda2fae0866546c3ee1c205fa8da8971fe Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rodolphe=20Br=C3=A9ard?= <v.code.ngyvz7vf@what.tf>
Date: Sun, 23 Jun 2024 10:20:57 +0200
Subject: [PATCH] Documenting errors

---
 src/error.rs | 25 +++++++++++++++++++++++--
 1 file changed, 23 insertions(+), 2 deletions(-)

diff --git a/src/error.rs b/src/error.rs
index f225373..2d2db1d 100644
--- a/src/error.rs
+++ b/src/error.rs
@@ -1,47 +1,68 @@
 pub(crate) type Result<T, E = Error> = core::result::Result<T, E>;
 
+/// An error type representing all the things that can go wrong.
 #[derive(thiserror::Error, Debug, PartialEq)]
 pub enum Error {
+	/// Something went wrong during the encryption or decryption using AES-GCM.
 	#[cfg(feature = "aes")]
 	#[error("cipher error: {0}")]
 	AesGcmError(aes_gcm::Error),
+	/// Something went wrong during the encryption or decryption using (X)ChaCha-poly1305.
 	#[cfg(feature = "chacha")]
 	#[error("cipher error: {0}")]
 	ChaCha20Poly1305Error(chacha20poly1305::Error),
+	/// The IKM list does not contain any usable IKM.
 	#[error("ikm error: no input key material available")]
 	IkmNoneAvailable,
+	/// The requested IKM has not been found in the list.
 	#[error("ikm error: {0}: input key material not found")]
 	IkmNotFound(crate::ikm::IkmId),
+	/// The nonce does not meet the required size.
 	#[error("encoded data: invalid nonce size: got {1} instead of {0}")]
 	InvalidNonceSize(usize, usize),
+	/// Something went wrong when encoding or decoding in base64.
 	#[error("parsing error: invalid base64-urlsafe-nopadding data: {0}")]
 	ParsingBase64Error(base64ct::Error),
+	/// When parsing some encoded data, an empty nonce has been encountered.
 	#[error("parsing error: encoded data: empty nonce")]
 	ParsingEncodedDataEmptyNonce,
+	/// When parsing some encoded data, an empty ciphertext has been encountered.
 	#[error("parsing error: encoded data: empty ciphertext")]
 	ParsingEncodedDataEmptyCiphertext,
+	/// When parsing some encoded data, an invalid IKM id has been encountered.
 	#[error("parsing error: encoded data: invalid IKM id: {0:?}")]
 	ParsingEncodedDataInvalidIkmId(Vec<u8>),
-	#[error("parsing error: encoded data: invalid IKM length{0}")]
+	/// When parsing some encoded data, an invalid IKM length has been encountered.
+	#[error("parsing error: encoded data: invalid IKM length: {0}")]
 	ParsingEncodedDataInvalidIkmLen(usize),
+	/// When parsing some encoded data, an invalid IKM list id has been encountered.
 	#[error("parsing error: encoded data: invalid IKM list id: {0:?}")]
 	ParsingEncodedDataInvalidIkmListId(Vec<u8>),
-	#[error("parsing error: encoded data: invalid IKM list length{0}")]
+	/// When parsing some encoded data, an invalid IKM list length has been encountered.
+	#[error("parsing error: encoded data: invalid IKM list length: {0}")]
 	ParsingEncodedDataInvalidIkmListLen(usize),
+	/// When parsing some encoded data, an invalid number of parts has been encountered.
 	#[error("parsing error: encoded data: invalid number of parts: got {1} instead of {0}")]
 	ParsingEncodedDataInvalidPartLen(usize, usize),
+	/// When parsing some encoded data, an invalid timestamp has been encountered.
 	#[error("parsing error: encoded data: invalid timestamp: {0:?}")]
 	ParsingEncodedDataInvalidTimestamp(Vec<u8>),
+	/// When parsing some encoded data, an invalid IKM list version has been encountered.
 	#[error("parsing error: encoded data: invalid IKML version")]
 	ParsingEncodedDataInvalidIkmlVersion,
+	/// When parsing some encoded data, an invalid encrypted data version has been encountered.
 	#[error("parsing error: encoded data: invalid encrypted data version")]
 	ParsingEncodedDataInvalidEncVersion,
+	/// An invalid scheme has been encountered.
 	#[error("parsing error: scheme: {0}: unknown scheme")]
 	ParsingSchemeUnknownScheme(crate::scheme::SchemeSerializeType),
+	/// Something went wrong when retrieving random data from the system.
 	#[error("unable to generate random values: {0}")]
 	RandomSourceError(getrandom::Error),
+	/// A `std::time::SystemTimeError` has been encountered.
 	#[error("system time error: {0}")]
 	SystemTimeError(String),
+	/// Something went wrong when trying to parse a timestamp.
 	#[error("system time error: {0}: unable to represent this timestamp as a system time")]
 	SystemTimeReprError(u64),
 }