(subplotlib): Add some doctests

Signed-off-by: Daniel Silverstone <dsilvers@digital-scurf.org>

4 files changed, 58 insertions, 0 deletions

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<ScenarioStep>)>,
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<dyn Fn(&ScenarioContext, bool) -> 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.