docs: add documentation comments to all public items that lack them

Some public items of the crate were undocumented. These items are now better
described in detail, and the missing docs pragma is added to catch further
missing items in the future.

Signed-off-by: Lars Wirzenius <liw@liw.fi>
Co-authored-by: Fintan Halpenny <fintan.halpenny@gmail.com>

src/error.rs

@@ -1,22 +1,49 @@
+//! Errors that are captured for job related actions.
+
 use radicle::{cob, git};
 use thiserror::Error;
 
+/// Errors that can occur when building a [`Job`][job].
+///
+/// [job]: super::Job
 #[derive(Debug, Error)]
 pub enum Build {
+    /// The initial action in the history of the [`Job`][job] was not a
+    /// [`Request`][req].
+    ///
+    /// [job]: super::Job
+    /// [req]: super::Action::Request
     #[error("initial action of job must request an OID")]
     Initial,
+    /// The [`Request`][req] referred to a commit that could not be found.
+    ///
+    /// [req]: super::Action::Request
     #[error("missing commit for job run {oid}: {err}")]
     MissingCommit {
+        /// The [`Oid`][oid] of the commit that was requested, but is missing.
+        ///
+        /// [oid]: git::Oid
         oid: git::Oid,
+        /// The underlying error from Git that occurred.
         #[source]
         err: git::Error,
     },
 }
 
+/// Errors that can occur when applying an [`Entry`][entry] to the [`Job`][job]
+/// collaborative object.
+///
+/// [entry]: radicle::cob::Entry
+/// [job]: super::Job
 #[derive(Debug, Error)]
 pub enum Apply {
+    /// Applying the entry resulted in a [`Build`] error.
     #[error(transparent)]
     Build(#[from] Build),
+    /// Error occurred when decoding an [`Entry`][entry] into an [`Op`][op].
+    ///
+    /// [entry]: radicle::cob::Entry
+    /// [op]: radicle::cob::Op
     #[error(transparent)]
     Op(#[from] cob::op::OpEncodingError),
 }

src/lib.rs

@@ -1,5 +1,13 @@
 //! Radicle "job COB".
 //!
+//! A [`Job`] records results of automated processing of a repository for a
+//! given Git commit, by one or more nodes.
+//!
+//! For any one of these processes there is a corresponding [`Run`]. For
+//! example, nodes that run CI for a repository might add `Run` to a `Job` for a
+//! specific commit. If there are several nodes running CI, they would each add
+//! their own `Run` to the same `Job`.
+//!
 //! # Example
 //!
 //! ```
@@ -39,6 +47,8 @@
 //! job.run(uuid, log, &alice.signer).unwrap();
 //! ```
 
+#![deny(missing_docs)]
+
 use std::collections::HashMap;
 use std::ops::{Deref, DerefMut};
 use std::str::FromStr;
@@ -409,7 +419,14 @@ impl<R: ReadRepository> Evaluate<R> for Job {
     }
 }
 
-/// A `Run` represents a task run for a [`Job`].
+/// A `Run` represents a task run for a [`Job`]. A `Run` is initially created in
+/// with a [`Status::Started`], before processing has started.
+///
+/// The `Run` can then be marked as [`Status::Finished`] with a given
+/// [`Reason`].
+///
+/// The `Run` also contains a [`Url`] so that any extra metadata, for example
+/// logs, can be tracked outside of the `Run` itself.
 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub struct Run {
     /// The status of the run.
@@ -424,6 +441,8 @@ pub struct Run {
 }
 
 impl Run {
+    /// Create a new `Run` with a [`Url`] that ideally points to the log of that
+    /// process.
     pub fn new(log: Url) -> Self {
         Self {
             status: Status::Started,
@@ -431,6 +450,7 @@ impl Run {
         }
     }
 
+    /// Mark the `Run` as finished.
     fn finish(self, reason: Reason) -> Self {
         Self {
             status: Status::Finished(reason),
@@ -438,10 +458,12 @@ impl Run {
         }
     }
 
+    /// Return latest [`Status`] of the `Run`.
     pub fn status(&self) -> &Status {
         &self.status
     }
 
+    /// Returns `true` if the status of the `Run` is [`Status::Started`].
     pub fn is_started(&self) -> bool {
         match self.status {
             Status::Started => true,
@@ -449,10 +471,13 @@ impl Run {
         }
     }
 
+    /// Returns `true` if the status of the `Run` is [`Status::Finished`].
     pub fn is_finished(&self) -> bool {
         !self.is_started()
     }
 
+    /// Returns `true` if the status of the `Run` is [`Status::Finished`] and
+    /// the reason for finishing is [`Reason::Succeeded`].
     pub fn succeeded(&self) -> bool {
         match self.status {
             Status::Started => false,
@@ -461,6 +486,8 @@ impl Run {
         }
     }
 
+    /// Returns `true` if the status of the `Run` is [`Status::Finished`] and
+    /// the reason for finishing is [`Reason::Failed`].
     pub fn failed(&self) -> bool {
         match self.status {
             Status::Started => false,
@@ -482,10 +509,25 @@ pub enum Status {
 /// The reason for a [`Status`] to have finished.
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub enum Reason {
+    /// The [`Run`] finished and failed.
     Failed,
+    /// The [`Run`] finished and succeeded.
     Succeeded,
 }
 
+/// The storage for all [`Job`] items.
+///
+/// To get a handle for [`Jobs`] use [`Jobs::open`].
+///
+/// The read-only operations for [`Jobs`] are:
+///
+///   - [`Jobs::counts`]
+///   - [`Jobs::get`]
+///
+/// The write operations for [`Jobs`] are:
+///
+///   - [`Jobs::create`]
+///   - [`Jobs::get_mut`]
 pub struct Jobs<'a, R> {
     raw: store::Store<'a, Job, R>,
 }
@@ -539,6 +581,7 @@ where
         })
     }
 
+    /// Create a new [`Job`] in the repository.
     pub fn create<'g, G>(
         &'g mut self,
         oid: Oid,
@@ -565,7 +608,10 @@ where
     }
 }
 
+/// A `JobMut` is a [`Job`] where the underlying `Job` can be mutated by
+/// applying actions to it.
 pub struct JobMut<'a, 'g, R> {
+    /// Git object that the [`Job`] applies to.
     pub id: ObjectId,
 
     job: Job,
@@ -584,15 +630,17 @@ impl<'a, 'g, R> JobMut<'a, 'g, R>
 where
     R: WriteRepository + cob::Store<Namespace = NodeId>,
 {
+    /// Create a new `JobMut`.
     pub fn new(id: ObjectId, job: Job, store: &'g mut Jobs<'a, R>) -> Self {
         Self { id, job, store }
     }
 
+    /// The COB identifier for the underlying [`Job`].
     pub fn id(&self) -> &ObjectId {
         &self.id
     }
 
-    /// Reload the patch data from storage.
+    /// Reload the [`Job`] data from underlying storage.
     pub fn reload(&mut self) -> Result<(), store::Error> {
         self.job = self
             .store
@@ -630,6 +678,7 @@ where
         self.transaction("Finished node job", signer, |tx| tx.finish(uuid, reason))
     }
 
+    /// Apply COB operations to a `JobMut`.
     pub fn transaction<G, F>(
         &mut self,
         message: &str,
@@ -650,6 +699,8 @@ where
     }
 }
 
+/// An update for the `Job` COB. This applies a change to the
+/// in-memory computed representation of the COB.
 pub struct Transaction<R: ReadRepository>(store::Transaction<Job, R>);
 
 impl<R> From<store::Transaction<Job, R>> for Transaction<R>
@@ -703,14 +754,17 @@ impl<R> Transaction<R>
 where
     R: ReadRepository,
 {
+    /// Add a request operation to the transaction.
     pub fn request(&mut self, oid: Oid) -> Result<(), store::Error> {
         self.0.push(Action::Request { oid })
     }
 
+    /// Add a new `Run` to a transaction.
     pub fn run(&mut self, uuid: Uuid, log: Url) -> Result<(), store::Error> {
         self.0.push(Action::Run { uuid, log })
     }
 
+    /// Mark a run as finished.
     pub fn finish(&mut self, uuid: Uuid, reason: Reason) -> Result<(), store::Error> {
         self.0.push(Action::Finished { uuid, reason })
     }