From 717cc8b0bc19a5c02b6180521969a4fd7789644a Mon Sep 17 00:00:00 2001
From: Paul Campbell <pcampbell@kemitix.net>
Date: Sat, 29 Jun 2024 14:56:20 +0100
Subject: [PATCH] refactor: update macro signatures and add documentation
 support

---
 crates/actor-macros/src/message.rs | 16 +++++------
 crates/config/src/branch_name.rs   |  3 +-
 crates/config/src/forge_alias.rs   |  3 +-
 crates/config/src/git_dir.rs       |  2 +-
 crates/config/src/host_name.rs     |  2 +-
 crates/config/src/newtype.rs       | 12 ++++----
 crates/config/src/repo_alias.rs    |  6 ++--
 crates/config/src/server.rs        |  3 +-
 crates/config/src/webhook/auth.rs  |  4 ++-
 crates/config/src/webhook/id.rs    |  2 +-
 crates/git/src/commit.rs           |  4 +--
 crates/git/src/generation.rs       |  4 ++-
 crates/git/src/git_ref.rs          |  2 +-
 crates/repo-actor/src/messages.rs  | 44 ++++++++++++++++++++++--------
 crates/repo-actor/src/tests/mod.rs |  2 +-
 crates/server-actor/src/lib.rs     |  6 +++-
 16 files changed, 69 insertions(+), 46 deletions(-)

diff --git a/crates/actor-macros/src/message.rs b/crates/actor-macros/src/message.rs
index 4a8e784..7056e84 100644
--- a/crates/actor-macros/src/message.rs
+++ b/crates/actor-macros/src/message.rs
@@ -1,25 +1,25 @@
 #[macro_export]
 macro_rules! message {
-    ($name:ident wraps $value:ty) => {
-        git_next_config::newtype!($name is a $value);
+    ($name:ident: $value:ty: $docs:literal) => {
+        git_next_config::newtype!($name: $value: $docs);
         impl actix::prelude::Message for $name {
             type Result = ();
         }
     };
-    ($name:ident) => {
-        git_next_config::newtype!($name);
+    ($name:ident: $docs:literal) => {
+        git_next_config::newtype!($name: $docs);
         impl actix::prelude::Message for $name {
             type Result = ();
         }
     };
-    ($name:ident wraps $value:ty => $result:ty) => {
-        git_next_config::newtype!($name is a $value);
+    ($name:ident: $value:ty => $result:ty: $docs:literal) => {
+        git_next_config::newtype!($name is a $value: $docs);
         impl actix::prelude::Message for $name {
             type Result = $result;
         }
     };
-    ($name:ident => $result:ty) => {
-        git_next_config::newtype!($name);
+    ($name:ident => $result:ty: $docs:literal) => {
+        git_next_config::newtype!($name: $docs);
         impl actix::prelude::Message for $name {
             type Result = $result;
         }
diff --git a/crates/config/src/branch_name.rs b/crates/config/src/branch_name.rs
index 1eb81cf..2d4ac67 100644
--- a/crates/config/src/branch_name.rs
+++ b/crates/config/src/branch_name.rs
@@ -1,2 +1 @@
-// The name of a Branch
-crate::newtype!(BranchName is a String, derive_more::Display, Default);
+crate::newtype!(BranchName: String, derive_more::Display, Default: "The name of a Git branch");
diff --git a/crates/config/src/forge_alias.rs b/crates/config/src/forge_alias.rs
index f8b5f29..cb362ae 100644
--- a/crates/config/src/forge_alias.rs
+++ b/crates/config/src/forge_alias.rs
@@ -1,5 +1,4 @@
-// The name of a Forge to connect to
-crate::newtype!(ForgeAlias is a String, Hash, derive_more::Display, Default);
+crate::newtype!(ForgeAlias: String, Hash, derive_more::Display, Default: "The name of a Forge to connect to");
 impl From<&ForgeAlias> for std::path::PathBuf {
     fn from(value: &ForgeAlias) -> Self {
         Self::from(&value.0)
diff --git a/crates/config/src/git_dir.rs b/crates/config/src/git_dir.rs
index b89222e..aad2c49 100644
--- a/crates/config/src/git_dir.rs
+++ b/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
diff --git a/crates/config/src/host_name.rs b/crates/config/src/host_name.rs
index f38a0e5..3f1bb89 100644
--- a/crates/config/src/host_name.rs
+++ b/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");
diff --git a/crates/config/src/newtype.rs b/crates/config/src/newtype.rs
index 038ad8c..63f2f01 100644
--- a/crates/config/src/newtype.rs
+++ b/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,
diff --git a/crates/config/src/repo_alias.rs b/crates/config/src/repo_alias.rs
index 3237576..39f0f0b 100644
--- a/crates/config/src/repo_alias.rs
+++ b/crates/config/src/repo_alias.rs
@@ -2,6 +2,6 @@ use derive_more::Display;
 
 use crate::newtype;
 
-// The alias of a repo
-// This is the alias for the repo within `git-next-server.toml`
-newtype!(RepoAlias is a String, Display, Default);
+newtype!(RepoAlias: String, Display, Default: r#"The alias of a repo.
+
+This is the alias for the repo within `git-next-server.toml`."#);
diff --git a/crates/config/src/server.rs b/crates/config/src/server.rs
index 0f76740..b042889 100644
--- a/crates/config/src/server.rs
+++ b/crates/config/src/server.rs
@@ -126,8 +126,7 @@ impl Webhook {
     }
 }
 
-// The RL for the webhook where forges should send their updates
-newtype!(WebhookUrl is a String, serde::Serialize);
+newtype!(WebhookUrl: String, serde::Serialize: "The URL for the webhook where forges should send their updates");
 
 /// The directory to store server data, such as cloned repos
 #[derive(
diff --git a/crates/config/src/webhook/auth.rs b/crates/config/src/webhook/auth.rs
index d61d593..c1768b6 100644
--- a/crates/config/src/webhook/auth.rs
+++ b/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 _;
diff --git a/crates/config/src/webhook/id.rs b/crates/config/src/webhook/id.rs
index 66fca94..d197944 100644
--- a/crates/config/src/webhook/id.rs
+++ b/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.");
diff --git a/crates/git/src/commit.rs b/crates/git/src/commit.rs
index 68f98a8..3bbcc1c 100644
--- a/crates/git/src/commit.rs
+++ b/crates/git/src/commit.rs
@@ -37,8 +37,8 @@ impl From<config::webhook::Push> for Commit {
     }
 }
 
-newtype!(Sha is a String, Display, Hash);
-newtype!(Message is a String, Hash);
+newtype!(Sha: String, Display, Hash: "The unique SHA for a git commit.");
+newtype!(Message: String, Hash: "The commit message for a git commit.");
 
 #[derive(Clone, Debug)]
 pub struct Histories {
diff --git a/crates/git/src/generation.rs b/crates/git/src/generation.rs
index 05cdbec..1339db5 100644
--- a/crates/git/src/generation.rs
+++ b/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
diff --git a/crates/git/src/git_ref.rs b/crates/git/src/git_ref.rs
index 6cc3764..f832e4b 100644
--- a/crates/git/src/git_ref.rs
+++ b/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())
diff --git a/crates/repo-actor/src/messages.rs b/crates/repo-actor/src/messages.rs
index 7f47589..bd24c25 100644
--- a/crates/repo-actor/src/messages.rs
+++ b/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!(CloneRepo);
-message!(ReceiveRepoConfig wraps config::RepoConfig);
-message!(ValidateRepo wraps MessageToken);
+message!(LoadConfigFromRepo: "Request to load the `git-next.toml` from the git repo.");
+message!(CloneRepo: "Request to clone (or open) the git repo.");
+message!(ReceiveRepoConfig: config::RepoConfig: r#"Notification that the `git-next.toml` file has been loaded from the repo and parsed.
 
-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!(CheckCIStatus wraps git::Commit); // next commit
-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
-message!(AdvanceMain wraps git::Commit); // next commit
-message!(WebhookNotification wraps config::webhook::forge_notification::ForgeNotification);
+message!(RegisterWebhook: "Requests that a Webhook be registered with the forge.");
+message!(CheckCIStatus: git::Commit: r#"Requests that the CI status for the commit be checked.
+
+Once the CI Status has been received it will be sent via a [ReceiveCIStatus] message.
+
+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.");
diff --git a/crates/repo-actor/src/tests/mod.rs b/crates/repo-actor/src/tests/mod.rs
index bb0938c..81d3b21 100644
--- a/crates/repo-actor/src/tests/mod.rs
+++ b/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;
 
diff --git a/crates/server-actor/src/lib.rs b/crates/server-actor/src/lib.rs
index a35c67f..dc13915 100644
--- a/crates/server-actor/src/lib.rs
+++ b/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 {