error-doc-impl 0.1.0

A simple proc macro to generate #[doc] comments from #[error] messages
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149

use proc_macro2::TokenStream;
use quote::quote;

/// This macro derives `thiserror::Error` and [`Debug`] traits, and automatically generates missing documents for error variants from error messages.
///
/// # Example
///
/// ```
/// #[error_doc::errors]
/// pub enum SomeError {
///     #[error("failed to open config file")]
///     OpenFile(#[from] std::io::Error),
///     #[error(transparent)]
///     #[doc = "Database error"]
///     Database(#[from] sqlx::Error),
///     #[error("unexpected value: `{0}`")]
///     #[doc = "Unexpected value is provided"]
///     UnexpectedValue(u16),
///     #[error("some other error")]
///     Other,
/// }
/// ```
///
/// generates
///
/// ```
/// #[derive(thiserror::Error, Debug)]
/// pub enum SomeError {
///     #[error("failed to open config file")]
///     #[doc = "Failed to open config file"]
///     OpenFile(#[from] std::io::Error),
///     #[error(transparent)]
///     #[doc = "Database error"]
///     Database(#[from] sqlx::Error),
///     #[error("unexpected value: `{0}`")]
///     #[doc = "Unexpected value is provided"]
///     UnexpectedValue(u16),
///     #[error("some other error")]
///     #[doc = "Some other error"]
///     Other,
/// }
/// ```
#[proc_macro_attribute]
pub fn errors(
    _attr: proc_macro::TokenStream,
    item: proc_macro::TokenStream,
) -> proc_macro::TokenStream {
    let item: TokenStream = match error_doc_impl(item.into()) {
        Ok(token_stream) => token_stream.into(),
        Err(error) => return error.to_compile_error().into(),
    };

    quote! {
        #[derive(::core::fmt::Debug, ::error_doc::thiserror::Error)]
        #item
    }
    .into()
}

/// This macro automatically generates missing documents for error variants from error messages.
///
/// # Example
///
/// ```rust
/// #[error_doc::error_doc]
/// #[derive(thiserror::Error, Debug)]
/// pub enum SomeError {
///     #[error("failed to open config file")]
///     OpenFile(#[from] std::io::Error),
///     #[error(transparent)]
///     #[doc = "Database error"]
///     Database(#[from] sqlx::Error),
///     #[error("unexpected value: `{0}`")]
///     #[doc = "Unexpected value is provided"]
///     UnexpectedValue(u16),
///     #[error("some other error")]
///     Other,
/// }
/// ```
///
/// generates
///
/// ```rust
/// #[error_doc::error_doc]
/// #[derive(thiserror::Error, Debug)]
/// pub enum SomeError {
///     #[error("failed to open config file")]
///     #[doc = "Failed to open config file"]
///     OpenFile(#[from] std::io::Error),
///     #[error(transparent)]
///     #[doc = "Database error"]
///     Database(#[from] sqlx::Error),
///     #[error("unexpected value: `{0}`")]
///     #[doc = "Unexpected value is provided"]
///     UnexpectedValue(u16),
///     #[error("some other error")]
///     #[doc = "Some other error"]
///     Other,
/// }
/// ```
#[proc_macro_attribute]
pub fn error_doc(
    _attr: proc_macro::TokenStream,
    item: proc_macro::TokenStream,
) -> proc_macro::TokenStream {
    match error_doc_impl(item.into()) {
        Ok(token_stream) => token_stream.into(),
        Err(error) => error.to_compile_error().into(),
    }
}

fn error_doc_impl(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()?;
                let mut msg = lit.value();

                // capitalize the first letter
                if let Some(first_letter) = msg.get_mut(..1) {
                    first_letter.make_ascii_uppercase();
                }

                Some(msg)
            });

            // add #[doc] attribute
            if let Some(msg) = msg {
                variant.attrs.push(syn::parse_quote! { #[doc = #msg] });
            }

            variant
        })
        .collect();

    Ok(quote! { #item })
}