From 9de12169a6715a0898f3b8280b5f2697826c11bc Mon Sep 17 00:00:00 2001
From: DarkCat09 <gh@dc09.ru>
Date: Thu, 8 Aug 2024 16:56:09 +0400
Subject: [PATCH] refactor: clean up errors; docs: add doc-comments to error.rs

---
 src/client/mod.rs |  2 +-
 src/error.rs      | 30 +++++++++++++++++++-----------
 2 files changed, 20 insertions(+), 12 deletions(-)

diff --git a/src/client/mod.rs b/src/client/mod.rs
index f13f865..820c3ba 100644
--- a/src/client/mod.rs
+++ b/src/client/mod.rs
@@ -99,7 +99,7 @@ impl Client {
     ///   Check the inner error if you need to determine what exactly happened
     /// - [`LibError::StatusOutOfRange`] means that a server returned an incorrect status code
     ///   (less than 10 or greater than 69).
-    /// - [`LibError::MessageNotUtf8`] is returned when metadata (the text after the status code)
+    /// - [`LibError::DataNotUtf8`] is returned when metadata (the text after a status code)
     ///   is not in UTF-8 and cannot be converted to string without errors.
     pub async fn request_with_host(
         &self,
diff --git a/src/error.rs b/src/error.rs
index fdfb0db..361d859 100644
--- a/src/error.rs
+++ b/src/error.rs
@@ -1,10 +1,19 @@
+//! Library error structures and enums
+
+/// Main error structure, also a wrapper for everything else
 #[derive(Debug)]
 pub enum LibError {
+    /// General I/O error
+    // TODO: separate somehow
     IoError(std::io::Error),
+    /// URL parse or check error
     InvalidUrlError(InvalidUrl),
+    /// Response status code is out of [10; 69] range
     StatusOutOfRange(u8),
-    MessageNotUtf8(std::string::FromUtf8Error),
-    BodyNotUtf8(std::str::Utf8Error),
+    /// Response metadata or content cannot be parsed
+    /// as a UTF-8 string without errors
+    DataNotUtf8(std::string::FromUtf8Error),
+    /// Provided string is not a valid MIME type
     InvalidMime(mime::FromStrError),
 }
 
@@ -39,14 +48,7 @@ impl LibError {
 impl From<std::string::FromUtf8Error> for LibError {
     #[inline]
     fn from(err: std::string::FromUtf8Error) -> Self {
-        Self::MessageNotUtf8(err)
-    }
-}
-
-impl From<std::str::Utf8Error> for LibError {
-    #[inline]
-    fn from(err: std::str::Utf8Error) -> Self {
-        Self::BodyNotUtf8(err)
+        Self::DataNotUtf8(err)
     }
 }
 
@@ -57,11 +59,17 @@ impl From<mime::FromStrError> for LibError {
     }
 }
 
+/// URL parse or check error
 #[derive(Debug)]
 pub enum InvalidUrl {
+    /// Provided string cannot be parsed as a valid URL with [`url::Url`]
     ParseError(url::ParseError),
+    /// URL scheme is not `gemini://`
     SchemeNotGemini,
+    /// URL contains userinfo -- `user:pswd@` --
+    /// which is forbidden by Gemini spec
     UserinfoPresent,
-    NoHostFound,
+    /// Could not extract host from the URL or convert host and port into
+    /// [`std::net::SocketAddr`] or [`crate::certs::ServerName`]
     ConvertError,
 }