From 229d47f7c7d61f62033101f7b48f8eefbc581ba6 Mon Sep 17 00:00:00 2001
From: Paul Campbell <pcampbell@kemitix.net>
Date: Sat, 13 Apr 2024 11:31:00 +0100
Subject: [PATCH] docs(server/config): add docs to types

---
 src/server/config.rs | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/src/server/config.rs b/src/server/config.rs
index e769e82..4d73144 100644
--- a/src/server/config.rs
+++ b/src/server/config.rs
@@ -9,6 +9,7 @@ use terrors::OneOf;
 
 use crate::filesystem::FileSystem;
 
+/// Mapped from the `git-next-server.toml` file
 #[derive(Debug, PartialEq, Eq, Deserialize)]
 pub struct ServerConfig {
     forge: HashMap<String, Forge>,
@@ -26,6 +27,9 @@ impl ServerConfig {
     }
 }
 
+/// Mapped from `.git-next.toml` file in target repo
+/// Is also derived from the optional parameters in `git-next-server.toml` at
+/// `forge.{forge}.repos.{repo}.(main|next|dev)`
 #[derive(Clone, Debug, PartialEq, Eq, Deserialize)]
 pub struct RepoConfig {
     branches: RepoBranches,
@@ -45,6 +49,8 @@ impl Display for RepoConfig {
         write!(f, "{:?}", self.branches)
     }
 }
+
+/// Mapped from `.git-next.toml` file at `branches`
 #[derive(Clone, Debug, PartialEq, Eq, Deserialize)]
 pub struct RepoBranches {
     main: String,
@@ -70,6 +76,8 @@ impl Display for RepoBranches {
     }
 }
 
+/// Defines a Forge to connect to
+/// Maps from `git-next-server.toml` at `forge.{forge}`
 #[derive(Clone, Debug, PartialEq, Eq, Deserialize)]
 pub struct Forge {
     forge_type: ForgeType,
@@ -110,6 +118,8 @@ impl Display for Forge {
     }
 }
 
+/// Defines a Repo within a Forge to be monitored by the server
+/// Maps from `git-next-server.toml` at `forge.{forge}.repos.{name}`
 #[derive(Clone, Debug, PartialEq, Eq, Deserialize)]
 pub struct Repo {
     repo: String,
@@ -137,6 +147,8 @@ impl Display for Repo {
         write!(f, "{} - {}", self.repo, self.branch)
     }
 }
+
+/// The name of a Forge to connect to
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct ForgeName(pub String);
 impl Display for ForgeName {
@@ -144,6 +156,8 @@ impl Display for ForgeName {
         write!(f, "{}", self.0)
     }
 }
+
+/// The hostname of a forge
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct Hostname(pub String);
 impl Display for Hostname {
@@ -151,6 +165,8 @@ impl Display for Hostname {
         write!(f, "{}", self.0)
     }
 }
+
+/// The user within the forge to connect as
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct User(pub String);
 impl Display for User {
@@ -158,6 +174,10 @@ impl Display for User {
         write!(f, "{}", self.0)
     }
 }
+
+/// The API Token for the [user]
+/// ForgeJo: https://{hostname}/user/settings/applications
+/// Github:  https://github.com/settings/tokens
 #[derive(Clone, Debug)]
 pub struct ApiToken(pub secrecy::Secret<String>);
 impl From<String> for ApiToken {
@@ -165,11 +185,14 @@ impl From<String> for ApiToken {
         Self(value.into())
     }
 }
+/// The API Token is in effect a password, so it must be explicitly exposed to access its value
 impl ExposeSecret<String> for ApiToken {
     fn expose_secret(&self) -> &String {
         self.0.expose_secret()
     }
 }
+
+/// The derived information about a Forge, used to create interactions with it
 #[derive(Clone, Debug)]
 pub struct ForgeDetails {
     pub name: ForgeName,
@@ -191,6 +214,9 @@ impl From<(&ForgeName, &Forge)> for ForgeDetails {
         }
     }
 }
+
+/// The name of a repo // TODO: (#39) rename as RepoAlias
+/// This is the alias for the repo within `git-next-server.toml`
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct RepoName(pub String);
 impl Display for RepoName {
@@ -198,6 +224,10 @@ impl Display for RepoName {
         write!(f, "{}", self.0)
     }
 }
+
+/// The path for the repo within the forge.
+/// Typically this is composed of the user or organisation and the name of the repo
+/// e.g. `{user}/{repo}`
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct RepoPath(pub String);
 impl Display for RepoPath {
@@ -205,6 +235,8 @@ impl Display for RepoPath {
         write!(f, "{}", self.0)
     }
 }
+
+/// The name of a Branch
 #[derive(Clone, Debug, Hash, PartialEq, Eq)]
 pub struct BranchName(pub String);
 impl Display for BranchName {
@@ -212,6 +244,8 @@ impl Display for BranchName {
         write!(f, "{}", self.0)
     }
 }
+
+/// The derived information about a repo, used to interact with it
 #[derive(Clone, Debug)]
 pub struct RepoDetails {
     pub name: RepoName,
@@ -251,6 +285,7 @@ impl Display for RepoDetails {
     }
 }
 
+/// Identifier for the type of Forge
 #[derive(Clone, Debug, PartialEq, Eq, Deserialize)]
 pub enum ForgeType {
     #[cfg(feature = "forgejo")]