2475066 docs: add documentation comments to all public items that lack them — radicle-job

rad:z2UcCU1LgMshWvXj6hXSDDrwB8q8M

Radicle Job Collaborative Object

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

Lars Wirzenius committed 10 months ago

commit 24750667f094f31ee6e5632563c9eba94e7ac953
parent 256242f

2 files changed +83 -2

modified 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),
 }

modified 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 })
     }