diff options
author | Justus Winter <justus@pep-project.org> | 2017-12-13 14:15:37 +0100 |
---|---|---|
committer | Justus Winter <justus@pep-project.org> | 2017-12-13 17:20:04 +0100 |
commit | 1e60568f020bd4f1cba2627784b849a9db293c52 (patch) | |
tree | c9a52b6759b8e3e157307618b6acd62f8647fd14 /core/src/lib.rs | |
parent | 21c5311ac2508745492de85f65088890e45073b7 (diff) |
core: Improve documentation.
Diffstat (limited to 'core/src/lib.rs')
-rw-r--r-- | core/src/lib.rs | 32 |
1 files changed, 28 insertions, 4 deletions
diff --git a/core/src/lib.rs b/core/src/lib.rs index efddaa0b..bbdd520f 100644 --- a/core/src/lib.rs +++ b/core/src/lib.rs @@ -5,23 +5,37 @@ use std::fs; use std::io; use std::path::{Path, PathBuf}; -/// A `&Context` is required for many operations. +/// A `&Context` for Sequoia. /// /// # Example /// +/// A context with reasonable defaults can be created using +/// `Context::new`: +/// /// ``` /// # use sequoia_core::Context; /// let c = Context::new("org.example.webmail").unwrap(); /// ``` +/// +/// A context can be configured using the builder pattern with +/// `Context::configure`: +/// +/// ``` +/// # use sequoia_core::Context; +/// let c = Context::configure("org.example.webmail") +/// .home("/tmp/foo") +/// .build().unwrap(); +/// ``` pub struct Context { domain: String, home: PathBuf, lib: PathBuf, } +/// Returns $PREXIX, or a reasonable default prefix. fn prefix() -> PathBuf { /* XXX: Windows support. */ - PathBuf::from(option_env!("PREFIX").or(Some("/usr/local")).unwrap()) + PathBuf::from(option_env!("PREFIX").unwrap_or("/usr/local")) } impl Context { @@ -69,10 +83,20 @@ impl Context { } /// Represents a `Context` configuration. +/// +/// A context can be configured using the builder pattern with +/// `Context::configure`: +/// +/// ``` +/// # use sequoia_core::Context; +/// let c = Context::configure("org.example.webmail") +/// .home("/tmp/foo") +/// .build().unwrap(); +/// ``` pub struct Config(Context); impl Config { - /// Finalizes the configuration and return a `Context`. + /// Finalizes the configuration and returns a `Context`. pub fn build(self) -> io::Result<Context> { let c = self.0; fs::create_dir_all(c.home())?; @@ -90,7 +114,7 @@ impl Config { self.0.home = PathBuf::new().join(home); } - /// Set the directory containing backend servers. + /// Sets the directory containing backend servers. pub fn lib<P: AsRef<Path>>(mut self, lib: P) -> Self { self.set_lib(lib); self |