diff options
author | Philipp Korber <p.korber@1aim.com> | 2018-11-20 18:04:10 +0100 |
---|---|---|
committer | Philipp Korber <p.korber@1aim.com> | 2018-11-20 18:04:10 +0100 |
commit | 5a743c9ef17347ecf7c00e518a844b8c25f4e90e (patch) | |
tree | c318f66dc3fece6806a3cfea715f593f983e7d3b | |
parent | 52c76d45550994e4f5947333d7f3ad4ce86cc860 (diff) |
doc: added simple documentation
-rw-r--r-- | src/lib.rs | 46 |
1 files changed, 30 insertions, 16 deletions
@@ -53,6 +53,7 @@ pub use self::base_dir::*; pub use self::path_rebase::*; pub use self::additional_cid::*; +/// Trait used to bind/implement template engines. pub trait TemplateEngine: Sized { type Id: Debug; @@ -65,6 +66,28 @@ pub trait TemplateEngine: Sized { -> Result<Self::Id, Error>; } +/// Additional trait a template engine needs to implement for the types it can process as input. +/// +/// This could for example be implemented in a wild card impl for the template engine for +/// any data `D` which implements `Serialize`. +pub trait TemplateEngineCanHandleData<D>: TemplateEngine { + + //TODO[doc]: this is needed for all template engines which use to json serialization + // (we have more then one template so there would be a lot of overhead) + type PreparedData: for<'a> BoundExt<'a>; + + //TODO[design]: allow returning a result + fn prepare_data<'a>(&self, raw: &'a D) -> PreparationData<'a, Self::PreparedData>; + + fn render<'r, 'a>( + &'r self, + id: &'r Self::Id, + data: &'r Bound<'a, Self::PreparedData>, + additional_cids: AdditionalCIds<'r> + ) -> Result<String, Error>; +} + +/// Load a template as described in a toml file. pub fn load_toml_template_from_path<TE, C>( engine: TE, path: PathBuf, @@ -81,6 +104,7 @@ pub fn load_toml_template_from_path<TE, C>( }).and_then(move |base| base.load(engine, &ctx2)) } +/// Load a template as described in a toml string; pub fn load_toml_template_from_str<TE, C>( engine: TE, content: &str, @@ -97,29 +121,15 @@ pub fn load_toml_template_from_str<TE, C>( Either::A(base.load(engine, ctx)) } +/// Compound POD for returning data needed for preparing for rendering a template. pub struct PreparationData<'a, PD: for<'any> BoundExt<'any>> { pub attachments: Vec<Resource>, pub inline_embeddings: HashMap<String, Resource>, pub prepared_data: Bound<'a, PD> } -pub trait TemplateEngineCanHandleData<D>: TemplateEngine { - - //TODO[doc]: this is needed for all template engines which use to json serialization - // (we have more then one template so there would be a lot of overhead) - type PreparedData: for<'a> BoundExt<'a>; - - //TODO[design]: allow returning a result - fn prepare_data<'a>(&self, raw: &'a D) -> PreparationData<'a, Self::PreparedData>; - - fn render<'r, 'a>( - &'r self, - id: &'r Self::Id, - data: &'r Bound<'a, Self::PreparedData>, - additional_cids: AdditionalCIds<'r> - ) -> Result<String, Error>; -} +/// A Mail template. #[derive(Debug)] pub struct Template<TE: TemplateEngine> { inner: Arc<InnerTemplate<TE>> @@ -215,6 +225,7 @@ impl<TE, D> TemplateExt<TE, D> for Template<TE> } } +/// Future returned when preparing a template for rendering. pub struct RenderPreparationFuture<'a, TE, D, C> where TE: TemplateEngine + TemplateEngineCanHandleData<D>, C: Context { @@ -254,6 +265,7 @@ impl<'a, TE,D,C> Future for RenderPreparationFuture<'a, TE, D, C> } } +/// Type containing the preparations done before rendering a template as Mail struct. pub struct Preparations<'a, TE, D, C> where TE: TemplateEngine + TemplateEngineCanHandleData<D>, C: Context { @@ -347,6 +359,7 @@ impl<'a, TE, D, C> Preparations<'a, TE, D, C> } } +/// Represents one of potentially many alternate bodies in a template. #[derive(Debug)] pub struct BodyTemplate<TE: TemplateEngine> { template_id: TE::Id, @@ -371,6 +384,7 @@ impl<TE> BodyTemplate<TE> } } +/// Represents a template used for generating the subject of a mail. #[derive(Debug)] pub struct Subject<TE: TemplateEngine> { template_id: TE::Id |