feat: add an example of generated code

To show what `typed_uuid` actually generates. It is behind a feature.

Author: dodomorandi

benzina/Cargo.toml

@@ -30,5 +30,7 @@ mysql = ["benzina-derive?/mysql"]
 serde = ["dep:serde", "uuid?/serde"]
 utoipa = ["dep:utoipa"]
 
+example-generated = ["typed-uuid"]
+
 [lints]
 workspace = true

benzina/src/example_generated.rs

@@ -0,0 +1,6 @@
+use crate::typed_uuid;
+
+typed_uuid!(
+    /// A example struct generated by [`typed_uuid`].
+    pub FooId
+);

benzina/src/lib.rs

@@ -5,6 +5,10 @@ pub use benzina_derive::Enum;
 
 #[cfg(feature = "postgres")]
 pub mod error;
+#[cfg(feature = "example-generated")]
+/// This module shows an example of code generated by the [`typed_uuid`] macro. IT **MUST NOT BE
+/// USED OUTSIDE THIS CRATE**.
+pub mod example_generated;
 #[cfg(feature = "postgres")]
 mod int;
 #[cfg(all(feature = "serde", feature = "postgres"))]

benzina/src/typed_uuid.rs

@@ -8,6 +8,17 @@
 /// order to provide the guarantee that the `UUID` is valid. However, it is possible to choose to
 /// add traits and methods to customize the behavior.
 ///
+#[cfg_attr(
+    not(feature = "example-generated"),
+    doc = "To see the documentation of a generated typed `UUID`, consider re-building the \
+        documentation with the feature `example-generated` enabled."
+)]
+#[cfg_attr(
+    feature = "example-generated",
+    doc = "You can see the documentation for an example generated `UUID` struct \
+        [`here`](crate::example_generated::FooId)."
+)]
+///
 /// [`Uuid`]: ::uuid::Uuid
 ///
 /// # Examples
@@ -146,12 +157,12 @@ macro_rules! typed_uuid {
 
             $crate::__typed_uuid__forward_from!(
                 $name:
-                    ::uuid::fmt::Braced,
-                    ::uuid::fmt::Hyphenated,
-                    ::uuid::fmt::Simple,
-                    ::uuid::fmt::Urn,
-                    ::std::string::String,
-                    ::std::vec::Vec<u8>,
+                ::uuid::fmt::Braced,
+                ::uuid::fmt::Hyphenated,
+                ::uuid::fmt::Simple,
+                ::uuid::fmt::Urn,
+                ::std::string::String,
+                ::std::vec::Vec<u8>,
             );
 
             impl ::std::fmt::Display for $name {
@@ -173,7 +184,7 @@ macro_rules! typed_uuid {
             }
 
             $crate::__typed_uuid__impl_serde!($name);
-        )+
+            )+
     };
 }