Mostly finish data source interactions

1 files changed, 29 insertions, 7 deletions

diff --git a/src/data/effective.rs b/src/data/effective.rs
index 12167dc..54b524f 100644
--- a/src/data/effective.rs
+++ b/src/data/effective.rs
@@ -14,8 +14,15 @@
 // You should have received a copy of the GNU Affero General Public License
 // along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
-//! A wrapper for [`DataSource`] that automatically handles
-//! [`OverridableKind`].
+//! Effective data sources and kinds.
+//!
+//! An [`EffectiveDataSource`] is a wrapper around [`DataSource`] that
+//! handles [`OverridableKind`], particularly those built around [`Vec`].
+//!
+//! An [`EffectiveKind`] is a wrapper around [`Kind`] that handles
+//! [`OverridableKind`], particularly those built around [`BTreeSet`].
+//!
+//! This asymmetry is necessary for the correct, order-dependent, semantics.
 
 use std::collections::BTreeSet;
 use std::collections::HashSet;
@@ -24,16 +31,25 @@ use std::time::Duration;
 
 use impl_trait::impl_trait;
 
-use super::DataSourceBase;
 use super::DataSource;
+use super::DataSourceBase;
 use super::Kind;
 use super::OverridableKind;
 
-/// A wrapper for [`DataSource`] that automatically handles
-/// [`OverridableKind`].
+#[cfg(test)]
+mod tests;
+
+/// A wrapper for [`DataSource`] that handles [`OverridableKind`].
+///
+/// This filters [`Vec`]-type [`Kind`]s to return only the first occurrence
+/// (by key) of a value.
+#[derive(Debug)]
 pub struct EffectiveDataSource<T: DataSourceBase>(T);
 
-/// A wrapper for [`OverridableKind`] that acts like the key for Eq/Hash/Ord.
+/// A wrapper for [`OverridableKind`] for use in [`BTreeSet`].
+///
+/// This compares like the key, allowing one to extend a [`BTreeSet`] and get
+/// the appropriate override semantics.
 #[repr(transparent)]
 #[derive(Debug)]
 pub struct EffectiveKind<T: OverridableKind>(pub T);
@@ -100,7 +116,7 @@ impl_trait! {
         /// Forwards to the inner [`DataSourceBase`].
         impl trait DataSourceBase {
             fn update(&mut self) -> (
-                Duration,
+                Option<Duration>,
                 Result<(), Box<dyn error::Error + Send + Sync + 'static>>,
             ) {
                 self.0.update()
@@ -111,6 +127,12 @@ impl_trait! {
             }
         }
 
+        impl trait std::fmt::Display {
+            fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
+                self.0.fmt(f)
+            }
+        }
+
         /// Filters the inner [`DataSource`] using the appropriate impl.
         impl trait<K: Kind> DataSource<K>
         where