From 381bdf14a91a97c6960f98504df8db5145e993f5 Mon Sep 17 00:00:00 2001
From: "Kevin R. Thornton" <krthornt@uci.edu>
Date: Wed, 15 Jun 2022 12:56:57 -0700
Subject: [PATCH] Document builder.rs (#113)

* Make API to add migration more convient.
---
 src/builder.rs | 195 +++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 182 insertions(+), 13 deletions(-)

diff --git a/src/builder.rs b/src/builder.rs
index 31cdc45a..dd0edfcc 100644
--- a/src/builder.rs
+++ b/src/builder.rs
@@ -1,3 +1,4 @@
+#![warn(missing_docs)]
 use crate::specification::Deme;
 use crate::specification::GenerationTime;
 use crate::specification::Graph;
@@ -10,12 +11,27 @@ use crate::specification::UnresolvedDemeHistory;
 use crate::specification::UnresolvedEpoch;
 use crate::DemesError;
 
+/// This type allows building a [`Graph`](crate::Graph) using code
+/// rather then using text input.
+///
+/// # Notes
+///
+/// * A "builder" in rust will never be as convenient
+///   as one in, say, Python or Juilia.
+///   The lack of a rust REPL and the strong type checking
+///   are the primary reasons.
+/// * All error checks are delayed until resolution.
 pub struct GraphBuilder {
     graph: Graph,
 }
 
 impl GraphBuilder {
-    // public API
+    /// Constructor
+    ///
+    /// # Returns
+    ///
+    /// This function returns an "builder" containing an unresolved
+    /// [`Graph`](crate::Graph).
     pub fn new(
         time_units: TimeUnits,
         generation_time: Option<GenerationTime>,
@@ -26,18 +42,29 @@ impl GraphBuilder {
         }
     }
 
+    /// Construct a builder with time units in generations.
+    ///
+    /// This function works by calling [`GraphBuilder::new`](crate::GraphBuilder::new).
     pub fn new_generations(defaults: Option<GraphDefaults>) -> Self {
         Self {
             graph: Graph::new(TimeUnits::Generations, None, defaults),
         }
     }
 
-    pub fn resolve(self) -> Result<Graph, DemesError> {
-        let mut builder = self;
-        builder.graph.resolve()?;
-        Ok(builder.graph)
-    }
-
+    /// Add a [`Deme`](crate::Deme) to the graph.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let start_size = demes::DemeSize::from(100.);
+    /// let epoch = demes::UnresolvedEpoch{start_size: Some(start_size), ..Default::default()};
+    /// let history = demes::UnresolvedDemeHistory::default();
+    /// let mut b = demes::GraphBuilder::new_generations(None);
+    /// b.add_deme("A", vec![epoch], history, Some("this is deme A"));
+    /// b.resolve().unwrap();
+    /// ```
+    ///
+    /// # Notes
     pub fn add_deme(
         &mut self,
         name: &str,
@@ -49,28 +76,170 @@ impl GraphBuilder {
         self.graph.add_deme(ptr);
     }
 
-    pub fn add_migration(
+    /// Add an asymmetric migration
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let start_size = demes::DemeSize::from(100.);
+    /// let epoch = demes::UnresolvedEpoch{start_size: Some(start_size), ..Default::default()};
+    /// let history = demes::UnresolvedDemeHistory::default();
+    /// let mut b = demes::GraphBuilder::new_generations(None);
+    /// b.add_deme("A", vec![epoch], history.clone(), Some("this is deme A"));
+    /// b.add_deme("B", vec![epoch], history, Some("this is deme B"));
+    /// b.add_asymmetric_migration(Some("A"),
+    ///                            Some("B"),
+    ///                            Some(demes::MigrationRate::from(1e-4)),
+    ///                            None, // Using None for the times
+    ///                                  // will mean continuous migration for the
+    ///                                  // duration for which the demes coexist.
+    ///                            None);
+    /// b.resolve().unwrap();
+    /// ```
+    pub fn add_asymmetric_migration<S: ToString, D: ToString>(
+        &mut self,
+        source: Option<S>,
+        dest: Option<D>,
+        rate: Option<MigrationRate>,
+        start_time: Option<Time>,
+        end_time: Option<Time>,
+    ) {
+        self.add_migration::<String, _, _>(None, source, dest, rate, start_time, end_time);
+    }
+
+    /// Add a symmetric migration
+    ///
+    /// # Examples
+    /// ```
+    /// let start_size = demes::DemeSize::from(100.);
+    /// let epoch = demes::UnresolvedEpoch{start_size: Some(start_size), ..Default::default()};
+    /// let history = demes::UnresolvedDemeHistory::default();
+    /// let mut b = demes::GraphBuilder::new_generations(None);
+    /// b.add_deme("A", vec![epoch], history.clone(), Some("this is deme A"));
+    /// b.add_deme("B", vec![epoch], history, Some("this is deme B"));
+    /// b.add_symmetric_migration(Some(&["A", "B"]),
+    ///                           Some(demes::MigrationRate::from(1e-4)),
+    ///                           None, // Using None for the times
+    ///                                 // will mean continuous migration for the
+    ///                                 // duration for which the demes coexist.
+    ///                           None);
+    /// b.resolve().unwrap();
+    /// ```
+    pub fn add_symmetric_migration<D: ToString>(
         &mut self,
-        demes: Option<Vec<String>>,
-        source: Option<String>,
-        dest: Option<String>,
+        demes: Option<&[D]>,
         rate: Option<MigrationRate>,
         start_time: Option<Time>,
         end_time: Option<Time>,
     ) {
+        self.add_migration::<_, String, String>(demes, None, None, rate, start_time, end_time);
+    }
+
+    /// Add an [`UnresolvedMigration`](crate::UnresolvedMigration) to the graph.
+    ///
+    /// # Note
+    ///
+    /// This function can be inconvenient due to the generics.
+    /// Prefer [`add_symmetric_migration`](crate::GraphBuilder::add_symmetric_migration)
+    /// or [`add_asymmetric_migration`](crate::GraphBuilder::add_asymmetric_migration).
+    ///
+    /// # Examples
+    ///
+    /// ## Adding an asymmetric migration
+    ///
+    /// ```
+    /// let start_size = demes::DemeSize::from(100.);
+    /// let epoch = demes::UnresolvedEpoch{start_size: Some(start_size), ..Default::default()};
+    /// let history = demes::UnresolvedDemeHistory::default();
+    /// let mut b = demes::GraphBuilder::new_generations(None);
+    /// b.add_deme("A", vec![epoch], history.clone(), Some("this is deme A"));
+    /// b.add_deme("B", vec![epoch], history, Some("this is deme B"));
+    /// b.add_migration::<String, _, _>(None,
+    ///                   Some("A"),
+    ///                   Some("B"),
+    ///                   Some(demes::MigrationRate::from(1e-4)),
+    ///                   None, // Using None for the times
+    ///                         // will mean continuous migration for the
+    ///                         // duration for which the demes coexist.
+    ///                   None);
+    /// b.resolve().unwrap();
+    /// ```
+    ///
+    /// ## Adding a symmetric migration
+    ///
+    /// ```
+    /// let start_size = demes::DemeSize::from(100.);
+    /// let epoch = demes::UnresolvedEpoch{start_size: Some(start_size), ..Default::default()};
+    /// let history = demes::UnresolvedDemeHistory::default();
+    /// let mut b = demes::GraphBuilder::new_generations(None);
+    /// b.add_deme("A", vec![epoch], history.clone(), Some("this is deme A"));
+    /// b.add_deme("B", vec![epoch], history, Some("this is deme B"));
+    /// b.add_migration::<_, String, String>(Some(&["A", "B"]),
+    ///                   None,
+    ///                   None,
+    ///                   Some(demes::MigrationRate::from(1e-4)),
+    ///                   None, // Using None for the times
+    ///                         // will mean continuous migration for the
+    ///                         // duration for which the demes coexist.
+    ///                   None);
+    /// b.resolve().unwrap();
+    /// ```
+    pub fn add_migration<D: ToString, S: ToString, E: ToString>(
+        &mut self,
+        demes: Option<&[D]>,
+        source: Option<S>,
+        dest: Option<E>,
+        rate: Option<MigrationRate>,
+        start_time: Option<Time>,
+        end_time: Option<Time>,
+    ) {
+        let demes = demes.map(|value| value.iter().map(|v| v.to_string()).collect::<Vec<_>>());
+        let source = source.map(|value| value.to_string());
+        let dest = dest.map(|value| value.to_string());
         self.graph
             .add_migration(demes, source, dest, rate, start_time, end_time);
     }
 
+    /// Add an [`UnresolvedPulse`](crate::UnresolvedPulse) to the graph.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let start_size = demes::DemeSize::from(100.);
+    /// let epoch = demes::UnresolvedEpoch{start_size: Some(start_size), ..Default::default()};
+    /// let history = demes::UnresolvedDemeHistory::default();
+    /// let mut b = demes::GraphBuilder::new_generations(None);
+    /// b.add_deme("A", vec![epoch], history.clone(), Some("this is deme A"));
+    /// b.add_deme("B", vec![epoch], history, Some("this is deme B"));
+    /// b.add_pulse(Some(&["A"]),
+    ///             Some("B"),
+    ///             Some(demes::Time::from(50.0)),
+    ///             Some(vec![demes::Proportion::from(0.5)]));
+    /// b.resolve().unwrap();
+    /// ```
     pub fn add_pulse(
         &mut self,
-        sources: Option<Vec<String>>,
-        dest: Option<String>,
+        sources: Option<&[&str]>,
+        dest: Option<&str>,
         time: Option<Time>,
         proportions: Option<Vec<Proportion>>,
     ) {
+        let sources = sources.map(|value| value.iter().map(|v| v.to_string()).collect::<Vec<_>>());
+        let dest = dest.map(|value| value.to_string());
         self.graph.add_pulse(sources, dest, time, proportions);
     }
+
+    /// Generate and return a resolved [`Graph`](crate::Graph).
+    ///
+    /// # Errors
+    ///
+    /// Returns [`DemesError'](crate::DemesError) if any
+    /// of the data are invalid.
+    pub fn resolve(self) -> Result<Graph, DemesError> {
+        let mut builder = self;
+        builder.graph.resolve()?;
+        Ok(builder.graph)
+    }
 }
 
 #[cfg(test)]