[refactor] hyperledger-iroha#3882: Clean up Emitter APIs documentatio…

…n to make clippy happy

Signed-off-by: Nikita Strygin <[email protected]>

macro/utils/src/emitter.rs

@@ -16,6 +16,7 @@ pub struct Emitter {
 }
 
 impl Emitter {
+    /// Creates a new emitter. It must be consumed by calling any of the `finish_*` functions before dropping or it will panic.
     pub fn new() -> Self {
         Self {
             inner: manyhow::Emitter::new(),
@@ -54,18 +55,32 @@ impl Emitter {
     }
 
     /// Consume the emitter, returning a [`manyhow::Error`] if any errors were emitted.
+    ///
+    /// # Errors
+    ///
+    /// This function returns an error if the emitter has some errors accumulated.
     pub fn finish(mut self) -> manyhow::Result<()> {
         self.bomb.defuse();
         self.inner.into_result()
     }
 
     /// Same as [`Emitter::finish`], but returns the given value if no errors were emitted.
+    ///
+    /// # Errors
+    ///
+    /// This function returns an error if the emitter has some errors accumulated.
     #[allow(unused)]
     pub fn finish_with<T>(self, result: T) -> manyhow::Result<T> {
         self.finish().map(|_| result)
     }
 
     /// Handles the given [`manyhow::Result`] and consumes the emitter.
+    ///
+    /// # Errors
+    ///
+    /// This function returns an error if:
+    /// - The given result is `Err`
+    /// - The emitter has some errors accumulated
     #[allow(unused)]
     pub fn finish_and<E: ToTokensError + 'static, T>(
         mut self,
@@ -81,7 +96,7 @@ impl Emitter {
     }
 
     /// Consume the emitter, convert all errors into a token stream and append it to the given token stream.
-    pub fn into_tokens(self, tokens: &mut TokenStream) {
+    pub fn finish_to_token_stream(self, tokens: &mut TokenStream) {
         match self.finish() {
             Ok(()) => {}
             Err(e) => e.to_tokens(tokens),
@@ -91,19 +106,25 @@ impl Emitter {
     /// Consume the emitter, convert all errors into a token stream.
     pub fn finish_token_stream(self) -> TokenStream {
         let mut tokens_stream = TokenStream::new();
-        self.into_tokens(&mut tokens_stream);
+        self.finish_to_token_stream(&mut tokens_stream);
         tokens_stream
     }
 
     /// Consume the emitter, convert all errors into a token stream and append it to the given token stream.
     ///
     /// This function is useful when you want to handle errors in a macro, but want to emit some tokens even in case of an error.
     pub fn finish_token_stream_with(self, mut tokens_stream: TokenStream) -> TokenStream {
-        self.into_tokens(&mut tokens_stream);
+        self.finish_to_token_stream(&mut tokens_stream);
         tokens_stream
     }
 }
 
+impl Default for Emitter {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
 impl<E: ToTokensError + 'static> Extend<E> for Emitter {
     fn extend<T: IntoIterator<Item = E>>(&mut self, iter: T) {
         self.inner.extend(iter)

macro/utils/src/lib.rs

@@ -76,7 +76,8 @@ macro_rules! attr_struct {
 pub trait DarlingErrorExt: Sized {
     /// Attaches a combination of multiple spans to the error.
     ///
-    /// Note that it only attaches the first span on stable rustc, as the `Span::join` method is not yet stabilized (https://github.com/rust-lang/rust/issues/54725#issuecomment-649078500).
+    /// Note that it only attaches the first span on stable rustc, as the `Span::join` method is not yet stabilized (<https://github.com/rust-lang/rust/issues/54725#issuecomment-649078500>).
+    #[must_use]
     fn with_spans(self, spans: impl IntoIterator<Item = impl Into<proc_macro2::Span>>) -> Self;
 }