From 2a4417efc4d0d578efc16a7e442278747cdb7a2c Mon Sep 17 00:00:00 2001 From: Daniel Silverstone Date: Sat, 26 Feb 2022 11:04:22 +0000 Subject: (subplotlib): Add some doctests Signed-off-by: Daniel Silverstone --- subplotlib/src/file.rs | 27 +++++++++++++++++++++++++++ subplotlib/src/scenario.rs | 15 +++++++++++++++ subplotlib/src/step.rs | 10 ++++++++++ subplotlib/src/utils.rs | 6 ++++++ 4 files changed, 58 insertions(+) (limited to 'subplotlib') diff --git a/subplotlib/src/file.rs b/subplotlib/src/file.rs index f695a89..b683c39 100644 --- a/subplotlib/src/file.rs +++ b/subplotlib/src/file.rs @@ -72,6 +72,12 @@ impl SubplotDataFile { /// /// Neither will be interpreted as utf8. /// + /// ``` + /// # use subplotlib::prelude::*; + /// + /// let data_file = SubplotDataFile::new("aGVsbG8=", "d29ybGQ="); + /// ``` + /// /// # Panics /// /// This will panic if the passed in strings are not correctly base64 encoded. @@ -85,11 +91,32 @@ impl SubplotDataFile { } /// Retrieve the filename + /// + /// File names are returned as a borrow of a [`Path`] since they could be + /// arbitrarily constructed, though typically they'll have come from markdown + /// source and so likely they will be utf-8 compatible. + /// + /// ``` + /// # use subplotlib::prelude::*; + /// let data_file = SubplotDataFile::new("aGVsbG8=", "d29ybGQ="); + /// assert_eq!(data_file.name().display().to_string(), "hello"); + /// ``` pub fn name(&self) -> &Path { &self.name } /// Retrieve the data + /// + /// The data of a file is always returned as a slice of bytes. This is because + /// files could be arbitrary data, though again, they typically will have been + /// sourced from a Subplot document and so be utf-8 compatible. + /// + /// ``` + /// # use subplotlib::prelude::*; + /// + /// let data_file = SubplotDataFile::new("aGVsbG8=", "d29ybGQ="); + /// assert_eq!(data_file.data(), b"world"); + /// ``` pub fn data(&self) -> &[u8] { &self.data } diff --git a/subplotlib/src/scenario.rs b/subplotlib/src/scenario.rs index c0f3e87..f382561 100644 --- a/subplotlib/src/scenario.rs +++ b/subplotlib/src/scenario.rs @@ -224,6 +224,21 @@ impl ScenarioContext { /// Scenario objects are built up by the generated test functions and then run /// to completion. In rare cases they may be built up and cached for reuse /// for example if a scenario is a subroutine. +/// +/// Scenarios are built from steps in sequence, and then can be run. +/// +/// ``` +/// # use subplotlib::prelude::*; +/// +/// let mut scenario = Scenario::new("example scenario"); +/// +/// let run_step = subplotlib::steplibrary::runcmd::run::Builder::default() +/// .argv0("true") +/// .args("") +/// .build(); +/// scenario.add_step(run_step, None); +/// +/// ``` pub struct Scenario { contexts: ScenarioContext, steps: Vec<(ScenarioStep, Option)>, diff --git a/subplotlib/src/step.rs b/subplotlib/src/step.rs index fba0216..b9c2a86 100644 --- a/subplotlib/src/step.rs +++ b/subplotlib/src/step.rs @@ -14,6 +14,16 @@ use crate::types::StepResult; /// /// In essence, a scenario step is a named closure. Its name can be used when /// reporting an error encountered in running a scenario. +/// +/// Scenario steps are typically constructed from step builders, rather than +/// directly. This permits the step builder to correctly register context types +/// etc. +/// +/// ``` +/// # use subplotlib::prelude::*; +/// +/// let step = ScenarioStep::new("step name", |ctx, ok| Ok(()), |scen| ()); +/// ``` pub struct ScenarioStep { name: String, func: Box StepResult>, diff --git a/subplotlib/src/utils.rs b/subplotlib/src/utils.rs index ee60f06..642848a 100644 --- a/subplotlib/src/utils.rs +++ b/subplotlib/src/utils.rs @@ -4,6 +4,12 @@ /// /// If the result is not a valid utf8 string then it is lossily coerced. /// +/// ``` +/// # use subplotlib::prelude::*; +/// +/// assert_eq!(base64_decode("aGVsbG8="), "hello"); +/// ``` +/// /// # Panics /// /// Will panic if it's not valid base64 leading to a string. -- cgit v1.2.1