833be8d docs: add documentation comments for everything in msg.src — radicle-ci-broker

Radicle CI broker

docs: add documentation comments for everything in msg.src

Lars Wirzenius committed 2 years ago

commit 833be8d0cc704b96db6a8468e959f7aca9a1b048
parent fe08cb9248c888759dcafa431795a98e8dbe0bbe

1 file changed +97 -5

modified src/msg.rs

@@ -2,7 +2,13 @@

 //!
 //! The broker spawns an adapter child process, and sends it a request
 //! via the child's stdin. The child sends responses via its stdout,
 //! which the broker reads and processes.
 //! which the broker reads and processes. These messages are
 //! represented using the types in this module.
 //!
 //! The types in this module are meant to be useful for anyone writing
 //! a Radicle CI adapter.
 #![deny(missing_docs)]
 use std::{
     fmt,

@@ -82,10 +88,15 @@ impl fmt::Display for RunResult {

 pub enum Request {
     /// Trigger a run.
     Trigger {
         /// Common fields for all message variants.
         #[serde(flatten)]
         common: EventCommonFields,
         /// The push event, if any.
         #[serde(flatten)]
         push: Option<PushEvent>,
         /// The patch event, if any.
         #[serde(flatten)]
         patch: Option<PatchEvent>,
     },

@@ -260,70 +271,145 @@ impl fmt::Display for Request {

     }
 }
 /// Common fields in all variations of a [`Request`] message.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct EventCommonFields {
     /// The type of the event.
     pub event_type: String,
     /// The repository the event is related to.
     pub repository: Repository,
 }
 /// A push event.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct PushEvent {
     /// The author of the change.
     pub pusher: Author,
     /// The commit on which the change is based.
     pub before: Oid,
     /// FIXME
     pub after: Oid,
     /// The commits in the change.
     pub commits: Vec<Oid>,
 }
 /// An event related to a Radicle patch object.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct PatchEvent {
     /// What action has happened to the patch. Should be one of
     /// `created` or `updated`.
     pub action: String,
     /// Metadata about the patch.
     pub patch: Patch,
 }
 /// Fields in a [`Request`] message describing the repository
 /// concerned.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Repository {
     /// The unique repository id.
     pub id: RepoId,
     /// The name of the repository.
     pub name: String,
     /// A description of the repository.
     pub description: String,
     /// Is it a private repository?
     pub private: bool,
     /// The default branch in the repository: the branch that gets
     /// updated when a change is merged.
     pub default_branch: String,
     /// The delegates of the repository: those who can actually merge
     /// the change.
     pub delegates: Vec<Did>,
 }
 /// Fields describing the author of a change.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Author {
     /// The DID of the author. This is guaranteed to be unique.
     pub id: Did,
     /// The alias, or name, of the author. This need not be unique.
     pub alias: Option<Alias>,
 }
 /// The state of a patch.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct State {
     /// State of the patch.
     pub status: String,
     /// FIXME.
     pub conflicts: Vec<(RevisionId, Oid)>,
 }
 /// Revision of a patch.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Revision {
     /// FIXME.
     pub id: Oid,
     /// Author of the revision.
     pub author: Author,
     /// Description of the revision.
     pub description: String,
     /// Base commit on which the revision of the patch should be
     /// applied.
     pub base: Oid,
     /// FIXME.
     pub oid: Oid,
     /// Time stamp of the revision.
     pub timestamp: u64,
 }
 /// Metadata about a Radicle patch.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Patch {
     /// The patch id.
     pub id: Oid,
     /// The author of the patch.
     pub author: Author,
     /// The title of the patch.
     pub title: String,
     /// The state of the patch.
     pub state: State,
     /// The commit preceding the patch.
     pub before: Oid,
     /// FIXME.
     pub after: Oid,
     /// The list of commits in the patch.
     pub commits: Vec<Oid>,
     /// FIXME.
     pub target: Oid,
     /// Labels assigned to the patch.
     pub labels: Vec<String>,
     /// Who're in charge of the patch.
     pub assignees: Vec<Did>,
     /// List of revisions of the patch.
     pub revisions: Vec<Revision>,
 }

@@ -334,10 +420,16 @@ pub struct Patch {

 #[serde(tag = "response")]
 pub enum Response {
     /// A CI run has been triggered.
     Triggered { run_id: RunId },
     Triggered {
         /// The identifier for the CI run assigned by the adapter.
         run_id: RunId,
     },
     /// A CI run has finished.
     Finished { result: RunResult },
     Finished {
         /// The result of a CI run.
         result: RunResult,
     },
 }
 impl Response {

@@ -397,12 +489,12 @@ impl Response {

 #[derive(Debug, thiserror::Error)]
 pub enum MessageError {
     /// Failed to serialize a request message as JSON. This should
     /// never happen and likely indicate a programming failure.
     /// never happen and likely indicates a programming failure.
     #[error("failed to serialize a request into JSON to a file handle")]
     SerializeRequest(#[source] serde_json::Error),
     /// Failed to serialize a response message as JSON. This should never
     /// happen and likely indicate a programming failure.
     /// happen and likely indicates a programming failure.
     #[error("failed to serialize a request into JSON to a file handle")]
     SerializeResponse(#[source] serde_json::Error),