refactor: update macro signatures and add documentation support

crates/actor-macros/src/message.rs

@@ -1,25 +1,25 @@
 #[macro_export]
 macro_rules! message {
-    ($name:ident wraps $value:ty) => {
+    ($name:ident: $value:ty: $docs:literal) => {
-        git_next_config::newtype!($name is a $value);
+        git_next_config::newtype!($name: $value: $docs);
         impl actix::prelude::Message for $name {
             type Result = ();
         }
     };
-    ($name:ident) => {
+    ($name:ident: $docs:literal) => {
-        git_next_config::newtype!($name);
+        git_next_config::newtype!($name: $docs);
         impl actix::prelude::Message for $name {
             type Result = ();
         }
     };
-    ($name:ident wraps $value:ty => $result:ty) => {
+    ($name:ident: $value:ty => $result:ty: $docs:literal) => {
-        git_next_config::newtype!($name is a $value);
+        git_next_config::newtype!($name is a $value: $docs);
         impl actix::prelude::Message for $name {
             type Result = $result;
         }
     };
-    ($name:ident => $result:ty) => {
+    ($name:ident => $result:ty: $docs:literal) => {
-        git_next_config::newtype!($name);
+        git_next_config::newtype!($name: $docs);
         impl actix::prelude::Message for $name {
             type Result = $result;
         }

crates/config/src/branch_name.rs

@@ -1,2 +1 @@
-// The name of a Branch
+crate::newtype!(BranchName: String, derive_more::Display, Default: "The name of a Git branch");
-crate::newtype!(BranchName is a String, derive_more::Display, Default);

crates/config/src/forge_alias.rs

@@ -1,5 +1,4 @@
-// The name of a Forge to connect to
+crate::newtype!(ForgeAlias: String, Hash, derive_more::Display, Default: "The name of a Forge to connect to");
-crate::newtype!(ForgeAlias is a String, Hash, derive_more::Display, Default);
 impl From<&ForgeAlias> for std::path::PathBuf {
     fn from(value: &ForgeAlias) -> Self {
         Self::from(&value.0)

crates/config/src/git_dir.rs

@@ -1,7 +1,7 @@
 //
 use std::path::PathBuf;
 
-crate::newtype!(GitDir is a PathBuf, Default);
+crate::newtype!(GitDir: PathBuf, Default: "The path to the directory containing the git repository.");
 impl GitDir {
     pub const fn pathbuf(&self) -> &PathBuf {
         &self.0

crates/config/src/host_name.rs

@@ -1,2 +1,2 @@
 // The hostname of a forge
-crate::newtype!(Hostname is a String, derive_more::Display, Default);
+crate::newtype!(Hostname: String, derive_more::Display, Default: "The hostname for the forge");

crates/config/src/newtype.rs

@@ -1,7 +1,8 @@
 //
 #[macro_export]
 macro_rules! newtype {
-    ($name:ident) => {
+    ($name:ident: $docs:literal) => {
+        #[doc = $docs]
         #[derive(
             Clone,
             Copy,
@@ -15,15 +16,12 @@ macro_rules! newtype {
             Ord,
             Hash,
             derive_more::AsRef,
+            derive_more::Constructor,
         )]
         pub struct $name;
-        impl $name {
-            pub fn new() -> Self {
-                Self
-            }
-        }
     };
-    ($name:ident is a $type:ty $(, $derive:ty)*) => {
+    ($name:ident: $type:ty $(, $derive:ty)*: $docs:literal) => {
+        #[doc = $docs]
         #[derive(
             Clone,
             Debug,

crates/config/src/repo_alias.rs

@@ -2,6 +2,6 @@ use derive_more::Display;
 
 use crate::newtype;
 
-// The alias of a repo
+newtype!(RepoAlias: String, Display, Default: r#"The alias of a repo.
-// This is the alias for the repo within `git-next-server.toml`
+
-newtype!(RepoAlias is a String, Display, Default);
+This is the alias for the repo within `git-next-server.toml`."#);

crates/config/src/server.rs

@@ -126,8 +126,7 @@ impl Webhook {
     }
 }
 
-// The RL for the webhook where forges should send their updates
+newtype!(WebhookUrl: String, serde::Serialize: "The URL for the webhook where forges should send their updates");
-newtype!(WebhookUrl is a String, serde::Serialize);
 
 /// The directory to store server data, such as cloned repos
 #[derive(

crates/config/src/webhook/auth.rs

@@ -1,5 +1,7 @@
 //
-crate::newtype!(WebhookAuth is a ulid::Ulid, derive_more::Display);
+crate::newtype!(WebhookAuth: ulid::Ulid, derive_more::Display: r#"The unique token authorisation for the webhook.
+
+Each monitored repository has it's own unique token, and it is different each time `git-next` runs."#);
 impl WebhookAuth {
     pub fn try_new(authorisation: &str) -> Result<Self, ulid::DecodeError> {
         use std::str::FromStr as _;

crates/config/src/webhook/id.rs

@@ -1,2 +1,2 @@
 //
-crate::newtype!(WebhookId is a String, derive_more::Display);
+crate::newtype!(WebhookId: String, derive_more::Display: "The ID of the webhook, as returned by the forge when it is registered.");

crates/git/src/commit.rs

@@ -37,8 +37,8 @@ impl From<config::webhook::Push> for Commit {
     }
 }
 
-newtype!(Sha is a String, Display, Hash);
+newtype!(Sha: String, Display, Hash: "The unique SHA for a git commit.");
-newtype!(Message is a String, Hash);
+newtype!(Message: String, Hash: "The commit message for a git commit.");
 
 #[derive(Clone, Debug)]
 pub struct Histories {

crates/git/src/generation.rs

@@ -1,7 +1,9 @@
 use derive_more::Display;
 use git_next_config::newtype;
 
-newtype!(Generation is a u32, Display, Default, Copy);
+newtype!(Generation: u32, Display, Default, Copy: r#"A counter for the server generation.
+
+This counter is increased by one each time the server restarts itself when the configuration file is updated."#);
 impl Generation {
     pub fn inc(&mut self) {
         self.0 += 1

crates/git/src/git_ref.rs

@@ -5,7 +5,7 @@ use git_next_config::newtype;
 
 use crate::Commit;
 
-newtype!(GitRef is a String, Display);
+newtype!(GitRef: String, Display: "A git reference to a git commit.");
 impl From<Commit> for GitRef {
     fn from(value: Commit) -> Self {
         Self(value.sha().to_string())

crates/repo-actor/src/messages.rs

@@ -6,12 +6,22 @@ use git_next_actor_macros::message;
 use git_next_config as config;
 use git_next_git as git;
 
-message!(LoadConfigFromRepo);
+message!(LoadConfigFromRepo: "Request to load the `git-next.toml` from the git repo.");
-message!(CloneRepo);
+message!(CloneRepo: "Request to clone (or open) the git repo.");
-message!(ReceiveRepoConfig wraps config::RepoConfig);
+message!(ReceiveRepoConfig: config::RepoConfig: r#"Notification that the `git-next.toml` file has been loaded from the repo and parsed.
-message!(ValidateRepo wraps MessageToken);
 
-message!(WebhookRegistered wraps (config::WebhookId, config::WebhookAuth));
+Contains the parsed contents of the `git-next.toml` file."#);
+message!(ValidateRepo: MessageToken: r#"Request that the state of the branches in the git repo be assessed and generate any followup actions.
+
+This is the main function of `git-next` where decisions are made on what branches need to be updated and when.
+
+Contains a [MessageToken] to reduce duplicate messages being sent. Only messages with the latest [MessageToken] are handled,
+all others are dropped."#);
+
+message!(WebhookRegistered: (config::WebhookId, config::WebhookAuth): r#"Notification that a webhook has been registered with a forge.
+
+Contains a tuple of the ID for the webhook returned from the forge, and the unique authorisation token that
+incoming messages from the forge must provide."#);
 impl WebhookRegistered {
     pub const fn webhook_id(&self) -> &config::WebhookId {
         &self.0 .0
@@ -28,16 +38,26 @@ impl From<config::RegisteredWebhook> for WebhookRegistered {
     }
 }
 
-newtype!(MessageToken is a u32, Copy, Default, Display);
+newtype!(MessageToken: u32, Copy, Default, Display: r#"An incremental token used to identify the current set of messages.
+
+Primarily used by [ValidateRepo] to reduce duplicate messages. The token is incremented when a new Webhook message is
+received, marking that message the latest, and causing any previous messages still being processed to be dropped when
+they next send a [ValidateRepo] message."#);
 impl MessageToken {
     pub const fn next(&self) -> Self {
         Self(self.0 + 1)
     }
 }
 
-message!(RegisterWebhook);
+message!(RegisterWebhook: "Requests that a Webhook be registered with the forge.");
-message!(CheckCIStatus wraps git::Commit); // next commit
+message!(CheckCIStatus: git::Commit: r#"Requests that the CI status for the commit be checked.
-message!(ReceiveCIStatus wraps (git::Commit, git::forge::commit::Status)); // commit and it's status
+
-message!(AdvanceNext wraps (git::Commit, Vec<git::Commit>)); // next commit and the dev commit history
+Once the CI Status has been received it will be sent via a [ReceiveCIStatus] message.
-message!(AdvanceMain wraps git::Commit); // next commit
+
-message!(WebhookNotification wraps config::webhook::forge_notification::ForgeNotification);
+Contains the commit from the tip of the `next` branch."#); // next commit
+message!(ReceiveCIStatus: (git::Commit, git::forge::commit::Status): r#"Notification of the status of the CI checks for the commit.
+
+Contains a tuple of the commit that was checked (the tip of the `next` branch) and the status."#); // commit and it's status
+message!(AdvanceNext: (git::Commit, Vec<git::Commit>): "Request to advance the `next` branch on to the next commit on the `dev branch."); // next commit and the dev commit history
+message!(AdvanceMain: git::Commit: "Request to advance the `main` branch on to same commit as the `next` branch."); // next commit
+message!(WebhookNotification: config::webhook::forge_notification::ForgeNotification: "Notification of a webhook message from the forge.");

crates/repo-actor/src/tests/mod.rs

@@ -68,7 +68,7 @@ impl RepoActorLog {
     }
 }
 
-message!(ExamineActor => RepoActorView);
+message!(ExamineActor => RepoActorView: "Request a view of the current state of the [RepoActor].");
 impl Handler<ExamineActor> for RepoActor {
     type Result = RepoActorView;
 

crates/server-actor/src/lib.rs

@@ -13,7 +13,11 @@ use std::path::PathBuf;
 use tracing::{error, info, warn};
 use webhook::{AddWebhookRecipient, ShutdownWebhook, WebhookActor, WebhookRouter};
 
-message!(ReceiveServerConfig wraps ServerConfig);
+message!(ReceiveServerConfig: ServerConfig: "Notification of newly loaded server configuration.
+
+This message will prompt the `git-next` server to stop and restart all repo-actors.
+
+Contains the new server configuration.");
 
 #[derive(Debug, derive_more::Display, derive_more::From)]
 pub enum Error {