doc/syns: more doc comments

kxxt · Jun 26, 2023 · 5b8c7d7 · 5b8c7d7
1 parent fcd8360
commit 5b8c7d7
Show file tree

Hide file tree

Showing 3 changed files with 26 additions and 2 deletions.
diff --git a/src/synthesizer/rest.rs b/src/synthesizer/rest.rs
@@ -11,6 +11,7 @@ use strum::AsRefStr;
 
 use crate::{interpolate_ssml, SsmlError, TextOptions};
 
+/// The synthesizer that uses the RESTful API.
 pub struct RestSynthesizer {
     pub(super) client: Client,
     pub(super) endpoint: String,
@@ -128,13 +129,21 @@ impl From<RestSynthesizerError> for pyo3::PyErr {
 #[non_exhaustive]
 #[strum(serialize_all = "title_case")]
 pub enum RestSynthesizerErrorKind {
+    /// Failed to connect to the endpoint.
     Connect,
+    /// The request was invalid, either caught early by us or indicated by a BadRequest response from the server.
     InvalidRequest,
+    /// You are unauthorized. Did you set up the correct auth key/token?
     Unauthorized,
+    /// The server returned a 415 Unsupported Media Type response.
     UnsupportedMediaType,
+    /// The server returned a 429 Too Many Requests response.
     TooManyRequests,
+    /// Other HTTP errors.
     OtherHttp,
+    /// Connection errors.
     Connection,
+    /// Errors when interpolating SSML.
     Ssml,
 }
 

diff --git a/src/synthesizer/unified.rs b/src/synthesizer/unified.rs
@@ -11,6 +11,7 @@ use crate::{interpolate_ssml, SsmlError, TextOptions};
 
 #[async_trait]
 pub trait UnifiedSynthesizer: Send {
+    /// Synthesize the given SSML into audio(Vec<u8>).
     async fn process_ssml(&mut self, ssml: &str) -> Result<Vec<u8>, UnifiedSynthesizerError>;
     /// This is a convenience method that interpolates the SSML for you.
     async fn process_text(
@@ -24,6 +25,7 @@ pub trait UnifiedSynthesizer: Send {
     }
 }
 
+/// Errors that can occur when creating and using a [`UnifiedSynthesizer`].
 #[derive(Debug)]
 #[non_exhaustive]
 pub struct UnifiedSynthesizerError {
@@ -64,11 +66,17 @@ impl From<UnifiedSynthesizerError> for pyo3::PyErr {
 #[non_exhaustive]
 #[strum(serialize_all = "title_case")]
 pub enum UnifiedSynthesizerErrorKind {
+    /// Failed to connect to the endpoint.
     Connect,
+    /// The request was invalid, either caught early by us or indicated by a BadRequest response from the server.
     InvalidRequest,
+    /// Http errors.
     Http,
+    /// Connection errors.
     Connection,
+    /// Invalid message received from the server.
     InvalidMessage,
+    /// Errors that occur while processing SSML.
     Ssml,
 }
 

diff --git a/src/synthesizer/websocket.rs b/src/synthesizer/websocket.rs
@@ -21,7 +21,7 @@ pub struct WebsocketSynthesizer {
 }
 
 impl WebsocketSynthesizer {
-    /// Synthesize the given SSML into audio(bytes).
+    /// Synthesize the given SSML into audio(Vec<u8>).
     pub async fn synthesize_ssml(
         &mut self,
         ssml: &str,
@@ -74,7 +74,7 @@ impl WebsocketSynthesizer {
         Ok(buffer)
     }
 
-    /// Synthesize the given text into audio(bytes).
+    /// Synthesize the given text into audio(Vec<u8>).
     /// This is a convenience method that interpolates the SSML for you.
     pub async fn synthesize_text(
         &mut self,
@@ -87,6 +87,7 @@ impl WebsocketSynthesizer {
     }
 }
 
+/// Errors that can occur when creating and using a [`WebsocketSynthesizer`].
 #[derive(Debug)]
 #[non_exhaustive]
 pub struct WebsocketSynthesizerError {
@@ -138,11 +139,17 @@ impl From<WebsocketSynthesizerError> for pyo3::PyErr {
 #[non_exhaustive]
 #[strum(serialize_all = "title_case")]
 pub enum WebsocketSynthesizerErrorKind {
+    /// Failed to connect to the endpoint.
     Connect,
+    /// The websocket connection was closed.
     WebsocketConnectionClosed { code: String, reason: String },
+    /// Other websocket errors.
     Websocket,
+    /// The request was invalid, either caught early by us or indicated by a BadRequest response from the server.
     InvalidRequest,
+    /// An invalid websocket message was received.
     InvalidMessage,
+    /// Errors that occur when interpolating SSML.
     Ssml,
 }