Generate doc-comments for generated errors (#25)

CHANGELOG.md

@@ -3,6 +3,7 @@
 This project follows semantic versioning.
 
 ### Unreleased
+- [fixed] Support for `#![deny(missing_docs)]`.
 
 ### 1.1.0 (2023-09-18)
 - [added] Default feature `std` and support for no-std.

Cargo.toml

@@ -16,6 +16,9 @@ keywords = ["enum", "sub-enum", "no-std"]
 proc-macro = true
 name = "subenum"
 
+[[example]]
+name = "require_docs"
+
 [dev-dependencies]
 derive_more = "0.99.17"
 strum = { version = "0.24.1", features = ["derive"], default-features = false }

examples/require_docs.rs

@@ -0,0 +1,19 @@
+#![deny(missing_docs)]
+//! An example of using subenum with `#![deny(missing_docs)]`.
+//!
+//! This is an example because the aforementioned attribute doesn't work in
+//! tests.
+
+use subenum::subenum;
+
+/// An enum.
+#[subenum(Bar)]
+pub enum Foo {
+    /// Variant A
+    #[subenum(Bar)]
+    A,
+    /// Variant B
+    B,
+}
+
+fn main() {}

src/build.rs

@@ -1,6 +1,6 @@
 use proc_macro2::TokenStream as TokenStream2;
 use quote::{format_ident, quote};
-use std::vec::Vec;
+use std::{format, vec::Vec};
 use syn::{punctuated::Punctuated, DeriveInput, Generics, Ident, Token, TypeParamBound, Variant};
 
 use crate::{
@@ -142,6 +142,10 @@ impl Enum {
 
         let (parent_impl, parent_ty, parent_where) = parent.generics.split_for_impl();
 
+        let error_doc = format!(
+            "An error type used for converting from [`{parent_ident}`] to [`{child_ident}`]."
+        );
+
         quote!(
             #(#[ #attributes ])*
             #(#child_attrs)*
@@ -151,6 +155,7 @@ impl Enum {
 
             #(#inherited_derives)*
 
+            #[doc = #error_doc]
             #[derive(Copy, Clone, Debug)]
             #vis struct #error;