doc

Author: forsaken628

src/common/base/macros/src/lib.rs

@@ -13,6 +13,36 @@ use syn::Type;
 use syn::parse_macro_input;
 use syn::parse_quote;
 
+/// Derives `::databend_common_base::base::Service` for a struct or enum.
+///
+/// Supported forms:
+/// - `#[derive(Service)]` on a struct or enum uses the default symbol
+///   `<TypeName>Symbol`.
+/// - `#[derive(Service)]` with `#[service_symbol(FooSymbol)]` uses an explicit
+///   service symbol.
+///
+/// # Examples
+///
+/// Default symbol:
+///
+/// ```ignore
+/// use databend_common_base::base::Service;
+///
+/// #[derive(Service)]
+/// pub struct MyService;
+/// ```
+///
+/// Explicit symbol:
+///
+/// ```ignore
+/// use databend_common_base::base::Service;
+///
+/// pub struct FooSymbol;
+///
+/// #[derive(Service)]
+/// #[service_symbol(FooSymbol)]
+/// pub struct MyService;
+/// ```
 #[proc_macro_derive(Service, attributes(service_symbol))]
 pub fn derive_service(item: TokenStream) -> TokenStream {
     let input = parse_macro_input!(item as DeriveInput);
@@ -28,6 +58,72 @@ pub fn derive_service(item: TokenStream) -> TokenStream {
     }
 }
 
+/// Assigns a `::databend_common_base::base::Service::Symbol` to a service type
+/// or `impl Service for ...` block.
+///
+/// Supported forms:
+/// - `#[service_symbol]` on a struct uses the default symbol
+///   `<TypeName>Symbol`.
+/// - `#[service_symbol(FooSymbol)]` on a struct uses an explicit symbol.
+/// - `#[service_symbol]` on an enum uses the default symbol
+///   `<TypeName>Symbol`.
+/// - `#[service_symbol(FooSymbol)]` on an enum uses an explicit symbol.
+/// - `#[service_symbol]` on a type alias uses the default symbol
+///   `<AliasName>Symbol`.
+/// - `#[service_symbol(FooSymbol)]` on a type alias uses an explicit symbol.
+/// - `#[service_symbol]` on `impl Service for T` uses the default symbol
+///   `<TypeName>Symbol`.
+/// - `#[service_symbol(FooSymbol)]` on `impl Service for T` uses an explicit
+///   symbol.
+///
+/// # Examples
+///
+/// Struct:
+///
+/// ```ignore
+/// use databend_common_base::base::service_symbol;
+///
+/// #[service_symbol]
+/// pub struct MyService;
+/// ```
+///
+/// Enum with an explicit symbol:
+///
+/// ```ignore
+/// use databend_common_base::base::service_symbol;
+///
+/// pub struct FooSymbol;
+///
+/// #[service_symbol(FooSymbol)]
+/// pub enum MyService {
+///     A,
+///     B,
+/// }
+/// ```
+///
+/// Type alias:
+///
+/// ```ignore
+/// use databend_common_base::base::service_symbol;
+///
+/// #[service_symbol]
+/// pub type BuildInfoRef = &'static BuildInfo;
+///
+/// pub struct BuildInfo;
+/// ```
+///
+/// Existing `impl Service for ...` block:
+///
+/// ```ignore
+/// use databend_common_base::base::Service;
+/// use databend_common_base::base::service_symbol;
+///
+/// pub struct FooSymbol;
+/// pub struct MyService;
+///
+/// #[service_symbol(FooSymbol)]
+/// impl Service for MyService {}
+/// ```
 #[proc_macro_attribute]
 pub fn service_symbol(attr: TokenStream, item: TokenStream) -> TokenStream {
     let item = parse_macro_input!(item as Item);