job: improve docs a little

src/job/mod.rs

@@ -1,10 +1,10 @@
 use actix_rt::Arbiter;
 use actix_web::web;
 use async_trait::async_trait;
+use serde::{Deserialize, Serialize};
 use std::sync::atomic::{AtomicUsize, Ordering};
 use std::sync::Weak;
 use std::time::Duration;
-use serde::{Deserialize, Serialize};
 use tokio::time::sleep;
 
 use crate::core::*;
@@ -19,9 +19,15 @@ const ERROR_DELAY: Duration = Duration::from_secs(5 * 60);
 /// enqueued it (which is usually a request handler).  This mechanism allows
 /// for fast response times to requests and automatic retries on failures
 /// such as network errors when a remote instance is currently offline.
+///
+/// [`Serialize`] and [`Deserialize`] are required for two reasons:
+/// Firstly, the server may be restarted between waiting for the next retry of
+/// failed jobs, in which case the parameters must be stored somewhere.
+/// Secondly, a future version may support executing jobs on a remote node,
+/// kind of like what Sidekiq does.
 #[async_trait]
 pub trait Job: Send + Sync + Serialize + Deserialize<'static> {
-    /// Execute the errand.
+    /// Fulfill the errand.
     ///
     /// This will be called by the scheduler in a background thread.
     /// If the result is an error, the scheduler may retry it again later.
@@ -29,7 +35,8 @@ pub trait Job: Send + Sync + Serialize + Deserialize<'static> {
 
     /// Return this job's name.
     ///
-    /// Currently only used for logging.
+    /// This should be unique per type of job, like for example the name of the
+    /// struct implementing this trait.  Currently only used for logging.
     fn name(&self) -> &'static str;
 }