docs: document errors

Author: robjtede

crates/oas3/CHANGELOG.md

@@ -3,6 +3,7 @@
 ## Unreleased
 
 - Expose the `spec::ClientCredentialsFlow::token_url` field.
+- Rename `Error::{SemVerError => Semver}` variant.
 
 ## 0.12.1
 

crates/oas3/src/error.rs

@@ -9,15 +9,19 @@ use crate::spec::Error as SpecError;
 /// Top-level errors.
 #[derive(Debug, Display, Error, From)]
 pub enum Error {
+    /// I/O error.
     #[display("I/O error")]
     Io(io::Error),
 
+    /// YAML error.
     #[display("YAML error")]
     Yaml(serde_yml::Error),
 
+    /// JSON error.
     #[display("JSON error")]
     Serialize(serde_json::Error),
 
+    /// Spec error.
     #[display("Spec error")]
     Spec(SpecError),
 }

crates/oas3/src/spec/error.rs

@@ -1,20 +1,24 @@
 use derive_more::derive::{Display, Error, From};
-use semver::{Error as SemVerError, Version};
+use semver::{Error as SemverError, Version};
 
 use crate::spec::{r#ref::RefError, schema::Error as SchemaError};
 
-/// Spec Errors
+/// Spec errors.
 #[derive(Debug, Display, Error, From)]
 pub enum Error {
+    /// Reference error.
     #[display("Reference error")]
     Ref(RefError),
 
+    /// Schema error.
     #[display("Schema error")]
     Schema(SchemaError),
 
+    /// Semver error.
     #[display("Semver error")]
-    SemVerError(SemVerError),
+    Semver(SemverError),
 
+    /// Unsupported spec file version.
     #[display("Unsupported spec file version ({})", _0)]
     UnsupportedSpecFileVersion(#[error(not(source))] Version),
 }