chore (backend-rs, macro-rs): separate error doc impl into another crate

Cargo.lock

@@ -213,6 +213,7 @@ dependencies = [
  "chrono",
  "cuid2",
  "emojis",
+ "error-doc",
  "futures-util",
  "identicon-rs",
  "idna 1.0.2",
@@ -945,6 +946,17 @@ dependencies = [
  "windows-sys 0.52.0",
 ]
 
+[[package]]
+name = "error-doc"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ffaad84523e0144697672bce3a0d8e300fd43404a630d420f238e2ef2e85b84"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.74",
+]
+
 [[package]]
 name = "etcetera"
 version = "0.8.0"

Cargo.toml

@@ -23,6 +23,7 @@ chrono = { version = "0.4.38", default-features = false }
 convert_case = { version = "0.6.0", default-features = false }
 cuid2 = { version = "0.1.2", default-features = false }
 emojis = { version = "0.6.3", default-features = false }
+error-doc = { version = "0.1.0" }
 futures-util = { version = "0.3.30", default-features = false }
 identicon-rs = "5.0.1"
 idna = { version = "1.0.2", default-features = false }

packages/backend-rs/Cargo.toml

@@ -27,6 +27,7 @@ bcrypt = { workspace = true, features = ["std"] }
 chrono = { workspace = true }
 cuid2 = { workspace = true }
 emojis = { workspace = true }
+error-doc = { workspace = true }
 futures-util = { workspace = true, features = ["io"] }
 identicon-rs = { workspace = true }
 idna = { workspace = true, features = ["std", "compiled_data"] }

packages/backend-rs/src/federation/activitypub/object/like.rs

@@ -9,10 +9,10 @@ use sea_orm::{ColumnTrait, DbErr, EntityTrait, QueryFilter, QuerySelect};
 
 #[macros::errors]
 pub enum Error {
-    #[doc = "nonexistent note"]
+    #[doc = "Nonexistent note"]
     #[error("note {0} not found")]
     NoteNotFound(String),
-    #[doc = "database error"]
+    #[doc = "Database error"]
     #[error(transparent)]
     Db(#[from] DbErr),
 }

packages/backend-rs/src/federation/internal_actor/instance.rs

@@ -12,7 +12,7 @@ pub enum Error {
     #[error("@instance.actor not found")]
     InstanceActorNotFound,
     #[error(transparent)]
-    #[doc = "database error"]
+    #[doc = "Database error"]
     Db(#[from] DbErr),
 }
 

packages/backend-rs/src/federation/internal_actor/relay.rs

@@ -12,7 +12,7 @@ pub enum Error {
     #[error("@relay.actor not found")]
     RelayActorNotFound,
     #[error(transparent)]
-    #[doc = "database error"]
+    #[doc = "Database error"]
     Db(#[from] DbErr),
 }
 

packages/backend-rs/src/federation/nodeinfo/fetch.rs

@@ -14,7 +14,7 @@ pub enum Error {
     HttpClient(#[from] http_client::Error),
     #[error("HTTP request failed")]
     Http(#[from] isahc::Error),
-    #[doc = "bad HTTP status"]
+    #[doc = "Bad HTTP status"]
     #[error("bad HTTP status ({0})")]
     BadStatus(String),
     #[error("failed to parse HTTP response body as text")]

packages/backend-rs/src/federation/nodeinfo/generate.rs

@@ -145,7 +145,7 @@ pub async fn nodeinfo_2_0() -> Result<Nodeinfo20, DbErr> {
 #[macros::for_ts]
 #[macros::errors]
 pub enum Error {
-    #[doc = "database error"]
+    #[doc = "Database error"]
     #[error(transparent)]
     Db(#[from] DbErr),
     #[error("failed to serialize nodeinfo into JSON")]

packages/backend-rs/src/misc/get_image_size.rs

@@ -15,7 +15,7 @@ pub enum Error {
     HttpClient(#[from] http_client::Error),
     #[error("HTTP request failed")]
     Isahc(#[from] isahc::Error),
-    #[doc = "bad HTTP status"]
+    #[doc = "Bad HTTP status"]
     #[error("bad HTTP status ({0})")]
     BadStatus(String),
     #[error("failed to decode an image")]
@@ -24,10 +24,10 @@ pub enum Error {
     Io(#[from] std::io::Error),
     #[error("failed to extract the exif data")]
     Exif(#[from] nom_exif::Error),
-    #[doc = "too many fetch attempts"]
+    #[doc = "Too many fetch attempts"]
     #[error("too many fetch attempts for {0}")]
     TooManyAttempts(String),
-    #[doc = "unsupported image type"]
+    #[doc = "Unsupported image type"]
     #[error("unsupported image type ({0})")]
     UnsupportedImage(String),
 }

packages/backend-rs/src/misc/random_icon.rs

@@ -4,7 +4,7 @@ use identicon_rs::{error::IdenticonError, Identicon};
 
 #[macros::errors]
 pub enum Error {
-    #[doc = "failed to generate identicon"]
+    #[doc = "Failed to generate identicon"]
     #[error(transparent)]
     Identicon(#[from] IdenticonError),
     #[error("Redis cache operation has failed")]

packages/backend-rs/src/misc/should_nyaify.rs

@@ -6,13 +6,13 @@ use sea_orm::{DbErr, EntityTrait, QuerySelect};
 
 #[macros::errors]
 pub enum Error {
-    #[doc = "database error"]
+    #[doc = "Database error"]
     #[error(transparent)]
     Db(#[from] DbErr),
-    #[doc = "cache error"]
+    #[doc = "Cache error"]
     #[error(transparent)]
     Cache(#[from] cache::redis::Error),
-    #[doc = "user not found"]
+    #[doc = "User not found"]
     #[error("user {0} not found")]
     NotFound(String),
 }

packages/backend-rs/src/misc/translate.rs

@@ -5,7 +5,7 @@ use crate::{
 
 #[macros::errors]
 pub enum Error {
-    #[doc = "database error"]
+    #[doc = "Database error"]
     #[error(transparent)]
     Db(#[from] sea_orm::DbErr),
     #[error("failed to acquire an HTTP client")]

packages/backend-rs/src/service/antenna/check_hit.rs

@@ -10,7 +10,7 @@ use sea_orm::{prelude::*, QuerySelect};
 
 #[macros::errors]
 pub enum AntennaCheckError {
-    #[doc = "database error"]
+    #[doc = "Database error"]
     #[error(transparent)]
     Db(#[from] DbErr),
     #[error("Redis cache operation has failed")]

packages/backend-rs/src/service/antenna/process_new_note.rs

@@ -16,7 +16,7 @@ use sea_orm::prelude::*;
 
 #[macros::errors]
 pub enum Error {
-    #[doc = "database error"]
+    #[doc = "Database error"]
     #[error(transparent)]
     Db(#[from] DbErr),
     #[error("Redis cache operation has failed")]
@@ -25,7 +25,7 @@ pub enum Error {
     Redis(#[from] RedisError),
     #[error("bad Redis connection")]
     RedisConn(#[from] RedisConnError),
-    #[doc = "provided string is not a valid Firefish ID"]
+    #[doc = "Provided string is not a valid Firefish ID"]
     #[error(transparent)]
     InvalidId(#[from] InvalidIdError),
     #[error("Redis stream operation has failed")]

packages/backend-rs/src/service/push_notification.rs

@@ -15,17 +15,17 @@ use web_push::*;
 
 #[macros::errors]
 pub enum Error {
-    #[doc = "database error"]
+    #[doc = "Database error"]
     #[error(transparent)]
     Db(#[from] DbErr),
     #[error("web push has failed")]
     WebPush(#[from] WebPushError),
     #[error("failed to (de)serialize an object")]
     Serialize(#[from] serde_json::Error),
-    #[doc = "provided content is invalid"]
+    #[doc = "Provided content is invalid"]
     #[error("invalid content ({0})")]
     InvalidContent(String),
-    #[doc = "found Mastodon subscription is invalid"]
+    #[doc = "Found Mastodon subscription is invalid"]
     #[error("invalid subscription ({0})")]
     InvalidSubscription(String),
     #[error("invalid notification ID")]

packages/macro-rs/macros-impl/src/error.rs

@@ -1,75 +0,0 @@
-//! Automatically generate doc comments for error variants from the error messages
-
-use proc_macro2::TokenStream;
-use quote::quote;
-
-/// Generates doc comments for error enums.
-///
-/// # Example
-/// ```
-/// # use macros_impl::error::error_variants as errors;
-/// # macros_impl::macro_doctest!({
-/// #[macros::errors]
-/// pub enum Error {
-///     #[error("config file name is not set")]
-///     NoConfigFileName,
-///     #[error("failed to read the config file")]
-///     ReadConfigFile(#[from] io::Error),
-///     #[error("invalid file content ({0})")]
-///     #[doc = "invalid file content"]
-///     InvalidContent(String),
-///     #[error(transparent)]
-///     #[doc = "database error"]
-///     Db(#[from] sea_orm::DbErr)
-/// }
-///
-/// # }, {
-/// /******* the code above expands to *******/
-///
-/// pub enum Error {
-///     #[error("config file name is not set")]
-///     #[doc = "config file name is not set"]
-///     NoConfigFileName,
-///     #[error("failed to read the config file")]
-///     #[doc = "failed to read the config file"]
-///     ReadConfigFile(#[from] io::Error),
-///     #[error("invalid file content ({0})")]
-///     #[doc = "invalid file content"]
-///     InvalidContent(String),
-///     #[error(transparent)]
-///     #[doc = "database error"]
-///     Db(#[from] sea_orm::DbErr)
-/// }
-/// # });
-/// ```
-pub fn error_variants(_attr: TokenStream, item: TokenStream) -> syn::Result<TokenStream> {
-    let mut item: syn::ItemEnum = syn::parse2(item)?;
-
-    item.variants = item
-        .variants
-        .into_iter()
-        .map(|mut variant| {
-            // check if doc attribute is alredy there
-            if variant.attrs.iter().any(|attr| attr.path().is_ident("doc")) {
-                return variant;
-            }
-
-            let msg = variant.attrs.iter().find_map(|attr| {
-                if !attr.path().is_ident("error") {
-                    return None;
-                }
-                let lit: syn::LitStr = attr.parse_args().ok()?;
-                Some(lit.value())
-            });
-
-            // add #[doc] attribute
-            if let Some(msg) = msg {
-                variant.attrs.push(syn::parse_quote! { #[doc = #msg] });
-            }
-
-            variant
-        })
-        .collect();
-
-    Ok(quote! { #item })
-}

packages/macro-rs/macros-impl/src/lib.rs

@@ -1,5 +1,4 @@
 #![allow(clippy::items_after_test_module)]
 
-pub mod error;
 pub mod napi;
 mod util;

packages/macro-rs/macros/src/lib.rs

@@ -84,11 +84,9 @@ define_wrapper_proc_macro_attributes! {
     /// When applied to enums, this macro implements [`std::error::Error`] trait
     /// and generates a document based on error messages unless there is already a doc comment
     ///
-    /// See [`macros_impl::error::error_variants`] for more details.
-    ///
     /// # Example
     ///
-    /// ```
+    /// ```ignore
     /// # use std::io;
     /// #[macros::errors]
     /// pub enum Error {
@@ -97,13 +95,13 @@ define_wrapper_proc_macro_attributes! {
     ///     #[error("failed to read the config file")]
     ///     ReadConfigFile(#[from] io::Error),
     ///     #[error("invalid file content ({0})")]
-    ///     #[doc = "invalid file content"]
+    ///     #[doc = "Invalid file content"]
     ///     InvalidContent(String),
     /// }
     /// ```
-    errors(attr, item) {
+    errors(_attr, item) {
         #[derive(::thiserror::Error, ::std::fmt::Debug)]
-        #[macros::error_variants(#attr, #item)]
+        #[error_doc::error_doc]
         #item
     }
 }
@@ -112,7 +110,4 @@ reexport_proc_macro_attributes! {
     /// Creates an extra wrapper function for [napi_derive](https://docs.rs/napi-derive/latest/napi_derive/).
     /// See [macros_impl::napi::napi] for details.
     macros_impl::napi::napi as napi
-
-    /// Generates doc comments for error variants from the error messages
-    macros_impl::error::error_variants as error_variants
 }