From 08e240d7dbb2af6d4eddcff2bcd820f7c61c2a1f Mon Sep 17 00:00:00 2001
From: Joscha <joscha@plugh.de>
Date: Sun, 13 Aug 2023 01:11:31 +0200
Subject: [PATCH] Fix and add documentation

---
 src/server/workers.rs | 4 ++--
 src/shared.rs         | 4 ++--
 src/worker/server.rs  | 5 +++--
 3 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/src/server/workers.rs b/src/server/workers.rs
index 386c971..8249897 100644
--- a/src/server/workers.rs
+++ b/src/server/workers.rs
@@ -91,7 +91,7 @@ impl Workers {
     }
 
     pub fn should_abort_work(&self, name: &str, queue: &[String]) -> bool {
-        // A runner should abort work if...
+        // A worker should abort work if...
         let Some(info) = self.workers.get(name) else { return false; };
         let WorkerStatus::Working (unfinished) = &info.status else { return false; };
 
@@ -100,7 +100,7 @@ impl Workers {
             return true;
         }
 
-        // Another runner has been working on the same commit for longer
+        // Another worker has been working on the same commit for longer
         let oldest_working_on_commit = self
             .workers
             .iter()
diff --git a/src/shared.rs b/src/shared.rs
index 7fb751e..8af4575 100644
--- a/src/shared.rs
+++ b/src/shared.rs
@@ -101,7 +101,7 @@ pub struct WorkerRequest {
     /// The worker wants a new run from the server.
     ///
     /// If the server has a commit available, it should respond with a non-null
-    /// [`ServerResponse::work`].
+    /// [`ServerResponse::run`].
     #[serde(default, skip_serializing_if = "is_false")]
     pub request_run: bool,
 
@@ -112,7 +112,7 @@ pub struct WorkerRequest {
 
 #[derive(Serialize, Deserialize)]
 pub struct ServerResponse {
-    /// Run the worker requested using [`RunnerRequest::request_run`].
+    /// Run the worker requested using [`WorkerRequest::request_run`].
     ///
     /// The worker may ignore this run and do something else. However, until the
     /// next update request sent by the worker, the server will consider the
diff --git a/src/worker/server.rs b/src/worker/server.rs
index ebed5a9..0695589 100644
--- a/src/worker/server.rs
+++ b/src/worker/server.rs
@@ -28,7 +28,7 @@ pub struct Server {
     /// while processing the response.
     ///
     /// This lock prevents the following race condition that would lead to
-    /// multiple runners receiving runs for the same commit in unlucky
+    /// multiple workers receiving runs for the same commit in unlucky
     /// circumstances:
     ///
     /// 1. The main task requests a run
@@ -40,7 +40,8 @@ pub struct Server {
 }
 
 impl Server {
-    // TODO Limit status requests to one in flight at a time (per server)
+    /// **Important:** Before using this function, read the documentation of
+    /// [`Self::status_lock`]!
     pub async fn post_status(
         &self,
         request_run: bool,