From 9a765f9d2b56274af39f2ae5cf858d7be649ddc1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <zecakeh@tedomum.fr>
Date: Sat, 30 Nov 2024 12:36:12 +0100
Subject: [PATCH] identifiers: Improve docs of IdZst macro

---
 crates/ruma-macros/src/lib.rs | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/crates/ruma-macros/src/lib.rs b/crates/ruma-macros/src/lib.rs
index 2c5f7e25..c73f5684 100644
--- a/crates/ruma-macros/src/lib.rs
+++ b/crates/ruma-macros/src/lib.rs
@@ -140,6 +140,39 @@ pub fn derive_from_event_to_enum(input: TokenStream) -> TokenStream {
 }
 
 /// Generate methods and trait impl's for ZST identifier type.
+///
+/// This macro generates an `Owned*` wrapper type for the identifier type. This wrapper type is
+/// variable, by default it'll use [`Box`], but it can be changed at compile time
+/// by setting `--cfg=ruma_identifiers_storage=...` using `RUSTFLAGS` or `.cargo/config.toml` (under
+/// `[build]` -> `rustflags = ["..."]`). Currently the only supported value is `Arc`, that uses
+/// [`Arc`](std::sync::Arc) as a wrapper type.
+///
+/// This macro implements:
+///
+/// * Conversions to and from string types, `AsRef<[u8]>` and `AsRef<str>`, as well as `as_str()`
+///   and `as_bytes()` methods. The borrowed type can be converted from a borrowed string without
+///   allocation.
+/// * Conversions to and from borrowed and owned type.
+/// * `Deref`, `AsRef` and `Borrow` to the borrowed type for the owned type.
+/// * `PartialEq` implementations for testing equality with string types and owned and borrowed
+///   types.
+///
+/// # Attributes
+///
+/// * `#[ruma_api(validate = PATH)]`: the path to a function to validate the string during parsing
+///   and deserialization. By default, the types implement `From` string types, when this is set
+///   they implement `TryFrom`.
+///
+/// # Examples
+///
+/// ```ignore
+/// # // HACK: This is "ignore" because of cyclical dependency drama.
+/// use ruma_macros::IdZst;
+///
+/// #[derive(PartialEq, Eq, PartialOrd, Ord, Hash, IdZst)]
+/// #[ruma_id(validate = ruma_identifiers_validation::user_id::validate)]
+/// pub struct UserId(str);
+/// ```
 #[proc_macro_derive(IdZst, attributes(ruma_id))]
 pub fn derive_id_zst(input: TokenStream) -> TokenStream {
     let input = parse_macro_input!(input as ItemStruct);