1 files changed, 23 insertions, 16 deletions
diff --git a/src/data.rs b/src/data.rs
index 3910dda..75ce565 100644
--- a/src/data.rs
+++ b/src/data.rs
@@ -14,9 +14,11 @@
 // 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/>.
 
-//! This module handles data source retrieval, parsing and processing.
+//! Data sources and their functionality.
 //!
-//! Data sources identify where to find repos and projects, among other things.
+//! Data sources are the primary means by which GAnarchy figures out what
+//! data to work with, and managers help combine and filter data sources into
+//! producing the desired data for the operation of an instance.
 
 use std::error;
 use std::hash::Hash;
@@ -25,20 +27,16 @@ use std::time::Duration;
 pub mod effective;
 pub mod kinds;
 pub mod managers;
+pub mod sources;
+
+#[cfg(test)]
+mod tests;
 
 /// A source of data.
-pub trait DataSourceBase {
-    /// Refreshes the data associated with this source, if necessary, and
-    /// returns the interval at which this should be called again.
-    ///
-    /// # Errors
-    ///
-    /// Returns an error if the source could not be updated. If an error is
-    /// returned, an attempt should be made to **not** invalidate this data
-    /// source, but instead carry on using stale data. Note that an aggregate
-    /// data source may partially update and return an aggregate error type.
+pub trait DataSourceBase: std::fmt::Display {
+    /// Refreshes the data associated with this source.
     fn update(&mut self) -> (
-        Duration,
+        Option<Duration>,
         Result<(), Box<dyn error::Error + Send + Sync + 'static>>,
     );
 
@@ -63,8 +61,8 @@ pub trait DataSource<T: Kind>: DataSourceBase {
 
     /// Returns the value associated with this kind.
     ///
-    /// This is the same as [`get_values`] but allows using the singular name,
-    /// for kinds with up to only one value.
+    /// This is the same as [`DataSource::get_values`] but allows using the
+    /// singular name, for kinds with up to only one value.
     ///
     /// # Panics
     ///
@@ -82,7 +80,7 @@ pub trait Kind {
 }
 
 /// A kind of value that can be retrieved from a data source, which can
-/// override values of the same kind.
+/// override values of the same kind based on a key.
 pub trait OverridableKind: Kind {
     /// The key, as in a map key, that gets overridden.
     type Key: Hash + Eq + Ord;
@@ -91,3 +89,12 @@ pub trait OverridableKind: Kind {
     /// a set such as `BTreeSet`.
     fn as_key(&self) -> &Self::Key;
 }
+
+/// Stats about an update.
+#[derive(Default)]
+pub struct Update {
+    /// Time until next refresh, if known.
+    pub refresh: Option<Duration>,
+    /// Errors collected in an update.
+    pub errors: Vec<Box<dyn error::Error + Send + Sync + 'static>>,
+}