From 862453174dc15e5184a4f86bb14f203ccef94de6 Mon Sep 17 00:00:00 2001 From: HampusM Date: Tue, 19 Sep 2023 20:37:28 +0200 Subject: docs: add examples to DI container & related functions --- .../asynchronous/binding/scope_configurator.rs | 91 +++++++++++++++++++++ .../asynchronous/binding/when_configurator.rs | 32 ++++++++ src/di_container/asynchronous/mod.rs | 92 ++++++++++++++++++++++ .../blocking/binding/scope_configurator.rs | 79 +++++++++++++++++++ .../blocking/binding/when_configurator.rs | 28 +++++++ src/di_container/blocking/mod.rs | 80 +++++++++++++++++++ 6 files changed, 402 insertions(+) diff --git a/src/di_container/asynchronous/binding/scope_configurator.rs b/src/di_container/asynchronous/binding/scope_configurator.rs index f079234..b63e644 100644 --- a/src/di_container/asynchronous/binding/scope_configurator.rs +++ b/src/di_container/asynchronous/binding/scope_configurator.rs @@ -47,6 +47,36 @@ where /// Configures the binding to be in a transient scope. /// /// This is the default. + /// + /// # Examples + /// ``` + /// # use syrette::{AsyncDIContainer, injectable}; + /// # + /// # struct Authenticator {} + /// # + /// # #[injectable(async = true)] + /// # impl Authenticator + /// # { + /// # fn new() -> Self + /// # { + /// # Self {} + /// # } + /// # } + /// # + /// # #[tokio::main] + /// # async fn main() -> Result<(), Box> { + /// let mut di_container = AsyncDIContainer::new(); + /// + /// di_container + /// .bind::() + /// .to::() + /// .await? + /// .in_transient_scope() + /// .await; + /// # + /// # Ok(()) + /// # } + /// ``` pub async fn in_transient_scope( self, ) -> AsyncBindingWhenConfigurator<'di_container, Interface> @@ -60,6 +90,67 @@ where /// /// # Errors /// Will return Err if resolving the implementation fails. + /// + /// # Examples + /// ``` + /// # use std::sync::atomic::{AtomicBool, Ordering}; + /// # use syrette::{AsyncDIContainer, injectable}; + /// # + /// # struct AudioManager + /// # { + /// # is_sound_playing: AtomicBool + /// # } + /// # + /// # #[injectable(async = true)] + /// # impl AudioManager + /// # { + /// # fn new() -> Self + /// # { + /// # Self { is_sound_playing: AtomicBool::new(false) } + /// # } + /// # + /// # fn play_long_sound(&self) + /// # { + /// # self.is_sound_playing.store(true, Ordering::Relaxed); + /// # } + /// # + /// # fn is_sound_playing(&self) -> bool + /// # { + /// # self.is_sound_playing.load(Ordering::Relaxed) + /// # } + /// # + /// # } + /// # + /// # #[tokio::main] + /// # async fn main() -> Result<(), Box> { + /// let mut di_container = AsyncDIContainer::new(); + /// + /// di_container + /// .bind::() + /// .to::() + /// .await? + /// .in_singleton_scope() + /// .await; + /// + /// { + /// let audio_manager = di_container + /// .get::() + /// .await? + /// .threadsafe_singleton()?; + /// + /// audio_manager.play_long_sound(); + /// } + /// + /// let audio_manager = di_container + /// .get::() + /// .await? + /// .threadsafe_singleton()?; + /// + /// assert!(audio_manager.is_sound_playing()); + /// # + /// # Ok(()) + /// # } + /// ``` pub async fn in_singleton_scope( self, ) -> Result< diff --git a/src/di_container/asynchronous/binding/when_configurator.rs b/src/di_container/asynchronous/binding/when_configurator.rs index b7c2767..bc8e97f 100644 --- a/src/di_container/asynchronous/binding/when_configurator.rs +++ b/src/di_container/asynchronous/binding/when_configurator.rs @@ -34,6 +34,38 @@ where /// /// # Errors /// Will return Err if no binding for the interface already exists. + /// + /// # Examples + /// ``` + /// # use syrette::{AsyncDIContainer, injectable}; + /// # + /// # struct Kitten {} + /// # + /// # #[injectable(async = true)] + /// # impl Kitten + /// # { + /// # fn new() -> Self + /// # { + /// # Self {} + /// # } + /// # } + /// # + /// # #[tokio::main] + /// # async fn main() -> Result<(), Box> { + /// let mut di_container = AsyncDIContainer::new(); + /// + /// di_container + /// .bind::() + /// .to::() + /// .await? + /// .in_transient_scope() + /// .await + /// .when_named("Billy") + /// .await?; + /// # + /// # Ok(()) + /// # } + /// ``` pub async fn when_named( self, name: &'static str, diff --git a/src/di_container/asynchronous/mod.rs b/src/di_container/asynchronous/mod.rs index 4be232d..929e2c0 100644 --- a/src/di_container/asynchronous/mod.rs +++ b/src/di_container/asynchronous/mod.rs @@ -93,6 +93,31 @@ impl AsyncDIContainer impl AsyncDIContainer { /// Returns a new [`AsyncBindingBuilder`] for the given interface. + /// + /// # Examples + /// ``` + /// # use syrette::{AsyncDIContainer, injectable}; + /// # + /// # struct DiskWriter {} + /// # + /// # #[injectable(async = true)] + /// # impl DiskWriter + /// # { + /// # fn new() -> Self + /// # { + /// # Self {} + /// # } + /// # } + /// # + /// # #[tokio::main] + /// # async fn main() -> Result<(), Box> { + /// let mut di_container = AsyncDIContainer::new(); + /// + /// di_container.bind::().to::().await?; + /// # + /// # Ok(()) + /// # } + /// ``` #[allow(clippy::missing_panics_doc)] pub fn bind(&mut self) -> AsyncBindingBuilder<'_, Interface> where @@ -112,6 +137,36 @@ impl AsyncDIContainer /// - No binding for `Interface` exists /// - Resolving the binding for `Interface` fails /// - Casting the binding for `Interface` fails + /// + /// # Examples + /// ``` + /// # use syrette::{AsyncDIContainer, injectable}; + /// # + /// # struct DeviceManager {} + /// # + /// # #[injectable(async = true)] + /// # impl DeviceManager + /// # { + /// # fn new() -> Self + /// # { + /// # Self {} + /// # } + /// # } + /// # + /// # #[tokio::main] + /// # async fn main() -> Result<(), Box> { + /// let mut di_container = AsyncDIContainer::new(); + /// + /// di_container + /// .bind::() + /// .to::() + /// .await?; + /// + /// let device_manager = di_container.get::().await?.transient(); + /// # + /// # Ok(()) + /// # } + /// ``` pub async fn get( &self, ) -> Result, AsyncDIContainerError> @@ -129,6 +184,43 @@ impl AsyncDIContainer /// - No binding for `Interface` with name `name` exists /// - Resolving the binding for `Interface` fails /// - Casting the binding for `Interface` fails + /// + /// # Examples + /// ``` + /// # use syrette::{AsyncDIContainer, injectable}; + /// # + /// # struct DeviceManager {} + /// # + /// # #[injectable(async = true)] + /// # impl DeviceManager + /// # { + /// # fn new() -> Self + /// # { + /// # Self {} + /// # } + /// # } + /// # + /// # #[tokio::main] + /// # async fn main() -> Result<(), Box> { + /// let mut di_container = AsyncDIContainer::new(); + /// + /// di_container + /// .bind::() + /// .to::() + /// .await? + /// .in_transient_scope() + /// .await + /// .when_named("usb") + /// .await; + /// + /// let device_manager = di_container + /// .get_named::("usb") + /// .await? + /// .transient(); + /// # + /// # Ok(()) + /// # } + /// ``` pub async fn get_named( &self, name: &'static str, diff --git a/src/di_container/blocking/binding/scope_configurator.rs b/src/di_container/blocking/binding/scope_configurator.rs index 3d939ba..ee935a5 100644 --- a/src/di_container/blocking/binding/scope_configurator.rs +++ b/src/di_container/blocking/binding/scope_configurator.rs @@ -47,6 +47,33 @@ where /// Configures the binding to be in a transient scope. /// /// This is the default. + /// + /// # Examples + /// ``` + /// # use syrette::{DIContainer, injectable}; + /// # + /// # struct Authenticator {} + /// # + /// # #[injectable] + /// # impl Authenticator + /// # { + /// # fn new() -> Self + /// # { + /// # Self {} + /// # } + /// # } + /// # + /// # fn main() -> Result<(), Box> { + /// let mut di_container = DIContainer::new(); + /// + /// di_container + /// .bind::() + /// .to::()? + /// .in_transient_scope(); + /// # + /// # Ok(()) + /// # } + /// ``` #[allow(clippy::must_use_candidate)] pub fn in_transient_scope(self) -> BindingWhenConfigurator<'di_container, Interface> { @@ -59,6 +86,58 @@ where /// /// # Errors /// Will return Err if resolving the implementation fails. + /// + /// # Examples + /// ``` + /// # use std::sync::atomic::{AtomicBool, Ordering}; + /// # use syrette::{DIContainer, injectable}; + /// # + /// # struct AudioManager + /// # { + /// # is_sound_playing: AtomicBool + /// # } + /// # + /// # #[injectable] + /// # impl AudioManager + /// # { + /// # fn new() -> Self + /// # { + /// # Self { is_sound_playing: AtomicBool::new(false) } + /// # } + /// # + /// # fn play_long_sound(&self) + /// # { + /// # self.is_sound_playing.store(true, Ordering::Relaxed); + /// # } + /// # + /// # fn is_sound_playing(&self) -> bool + /// # { + /// # self.is_sound_playing.load(Ordering::Relaxed) + /// # } + /// # + /// # } + /// # + /// # fn main() -> Result<(), Box> { + /// let mut di_container = DIContainer::new(); + /// + /// di_container + /// .bind::() + /// .to::()? + /// .in_singleton_scope(); + /// + /// { + /// let audio_manager = di_container.get::()?.singleton()?; + /// + /// audio_manager.play_long_sound(); + /// } + /// + /// let audio_manager = di_container.get::()?.singleton()?; + /// + /// assert!(audio_manager.is_sound_playing()); + /// # + /// # Ok(()) + /// # } + /// ``` pub fn in_singleton_scope( self, ) -> Result< diff --git a/src/di_container/blocking/binding/when_configurator.rs b/src/di_container/blocking/binding/when_configurator.rs index 2a1af2c..d23d213 100644 --- a/src/di_container/blocking/binding/when_configurator.rs +++ b/src/di_container/blocking/binding/when_configurator.rs @@ -34,6 +34,34 @@ where /// /// # Errors /// Will return Err if no binding for the interface already exists. + /// + /// # Examples + /// ``` + /// # use syrette::{DIContainer, injectable}; + /// # + /// # struct Kitten {} + /// # + /// # #[injectable] + /// # impl Kitten + /// # { + /// # fn new() -> Self + /// # { + /// # Self {} + /// # } + /// # } + /// # + /// # fn main() -> Result<(), Box> { + /// let mut di_container = DIContainer::new(); + /// + /// di_container + /// .bind::() + /// .to::()? + /// .in_transient_scope() + /// .when_named("Billy")?; + /// # + /// # Ok(()) + /// # } + /// ``` pub fn when_named( self, name: &'static str, diff --git a/src/di_container/blocking/mod.rs b/src/di_container/blocking/mod.rs index 69efe9a..df6e68c 100644 --- a/src/di_container/blocking/mod.rs +++ b/src/di_container/blocking/mod.rs @@ -95,6 +95,30 @@ impl DIContainer impl DIContainer { /// Returns a new [`BindingBuilder`] for the given interface. + /// + /// # Examples + /// ``` + /// # use syrette::{DIContainer, injectable}; + /// # + /// # struct DiskWriter {} + /// # + /// # #[injectable] + /// # impl DiskWriter + /// # { + /// # fn new() -> Self + /// # { + /// # Self {} + /// # } + /// # } + /// # + /// # fn main() -> Result<(), Box> { + /// let mut di_container = DIContainer::new(); + /// + /// di_container.bind::().to::()?; + /// # + /// # Ok(()) + /// # } + /// ``` #[allow(clippy::missing_panics_doc)] pub fn bind(&mut self) -> BindingBuilder<'_, Interface> where @@ -114,6 +138,32 @@ impl DIContainer /// - No binding for `Interface` exists /// - Resolving the binding for `Interface` fails /// - Casting the binding for `Interface` fails + /// + /// # Examples + /// ``` + /// # use syrette::{DIContainer, injectable}; + /// # + /// # struct DeviceManager {} + /// # + /// # #[injectable] + /// # impl DeviceManager + /// # { + /// # fn new() -> Self + /// # { + /// # Self {} + /// # } + /// # } + /// # + /// # fn main() -> Result<(), Box> { + /// let mut di_container = DIContainer::new(); + /// + /// di_container.bind::().to::()?; + /// + /// let device_manager = di_container.get::()?.transient(); + /// # + /// # Ok(()) + /// # } + /// ``` pub fn get(&self) -> Result, DIContainerError> where Interface: 'static + ?Sized, @@ -128,6 +178,36 @@ impl DIContainer /// - No binding for `Interface` with name `name` exists /// - Resolving the binding for `Interface` fails /// - Casting the binding for `Interface` fails + /// + /// # Examples + /// ``` + /// # use syrette::{DIContainer, injectable}; + /// # + /// # struct DeviceManager {} + /// # + /// # #[injectable] + /// # impl DeviceManager + /// # { + /// # fn new() -> Self + /// # { + /// # Self {} + /// # } + /// # } + /// # + /// # fn main() -> Result<(), Box> { + /// let mut di_container = DIContainer::new(); + /// + /// di_container + /// .bind::() + /// .to::()? + /// .in_transient_scope() + /// .when_named("usb")?; + /// + /// let device_manager = di_container.get_named::("usb")?.transient(); + /// # + /// # Ok(()) + /// # } + /// ``` pub fn get_named( &self, name: &'static str, -- cgit v1.2.3-18-g5258