From 88ec1a0a5611950957704f4c16038f7e76aad3d0 Mon Sep 17 00:00:00 2001 From: "coderabbitai[bot]" <136622811+coderabbitai[bot]@users.noreply.github.com> Date: Fri, 1 Aug 2025 11:33:14 +0000 Subject: [PATCH 1/2] =?UTF-8?q?=F0=9F=93=9D=20Add=20docstrings=20to=20`cod?= =?UTF-8?q?ex/add-post=5Fcomment-function-and-integrate`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Docstrings generation was requested by @leynos. * https://github.com/leynos/comenq/pull/22#issuecomment-3133441378 The following files were modified: * `crates/comenqd/src/daemon.rs` --- crates/comenqd/src/daemon.rs | 85 ++++++++++++++++++++++++++++-------- 1 file changed, 67 insertions(+), 18 deletions(-) diff --git a/crates/comenqd/src/daemon.rs b/crates/comenqd/src/daemon.rs index 7b28949..423e4e7 100644 --- a/crates/comenqd/src/daemon.rs +++ b/crates/comenqd/src/daemon.rs @@ -31,6 +31,21 @@ enum PostCommentError { Timeout, } +/// Constructs an authenticated Octocrab GitHub client using a personal access token. +/// +/// # Arguments +/// +/// * `token` - A GitHub personal access token used for authentication. +/// +/// # Returns +/// +/// Returns an `Octocrab` client instance on success, or an error if the client could not be built. +/// +/// # Examples +/// +/// ```no_run +/// let octocrab = build_octocrab("ghp_exampletoken123")?; +/// ``` fn build_octocrab(token: &str) -> Result { Ok(Octocrab::builder() .personal_token(token.to_string()) @@ -46,12 +61,44 @@ fn prepare_listener(path: &Path) -> Result { Ok(listener) } +/// Asynchronously creates the queue directory and all necessary parent directories if they do not exist. +/// +/// # Examples +/// +/// ```no_run +/// use std::path::Path; +/// # tokio_test::block_on(async { +/// ensure_queue_dir(Path::new("/tmp/comenqd-queue")).await.unwrap(); +/// # }); +/// ``` async fn ensure_queue_dir(path: &Path) -> Result<()> { fs::create_dir_all(path).await?; Ok(()) } -/// Post a comment to GitHub with a 10 second timeout. +/// Attempts to post a comment to a GitHub pull request, enforcing a 10-second timeout. +/// +/// Returns `Ok(())` if the comment is successfully posted. If the GitHub API returns an error, +/// returns `PostCommentError::Api`. If the operation does not complete within 10 seconds, +/// returns `PostCommentError::Timeout`. +/// +/// # Examples +/// +/// ```no_run +/// # use comenqd::{post_comment, CommentRequest, PostCommentError}; +/// # use octocrab::Octocrab; +/// # async fn example() -> Result<(), PostCommentError> { +/// let octocrab = Octocrab::builder().personal_token("token").build().unwrap(); +/// let request = CommentRequest { +/// owner: "owner".to_string(), +/// repo: "repo".to_string(), +/// pr_number: 1, +/// body: "Test comment".to_string(), +/// }; +/// post_comment(&octocrab, &request).await?; +/// # Ok(()) +/// # } +/// ``` async fn post_comment( octocrab: &Octocrab, request: &CommentRequest, @@ -208,27 +255,29 @@ async fn handle_client(mut stream: UnixStream, tx: mpsc::UnboundedSender Ok(()) } -/// Dequeue requests and post comments to GitHub with a cooldown. +/// Processes queued comment requests and posts them to GitHub, enforcing a cooldown between attempts. /// -/// The worker continuously reads entries from the `yaque` queue and posts each -/// comment through the provided [`Octocrab`] instance. Successful posts commit -/// the queue entry, removing it from disk. Failures leave the message -/// uncommitted so it is retried on the next loop iteration. +/// Continuously receives comment requests from the persistent queue, attempts to post each comment to GitHub using the provided client, and commits successfully processed entries to remove them from the queue. Failed requests remain in the queue for retry. A fixed cooldown period, specified in the configuration, is applied after each attempt regardless of outcome. There is no exponential backoff; all retries use the same cooldown interval. /// -/// A cooldown period, configured via [`Config`], is enforced **between all -/// requests**, regardless of success or failure. After each attempt the worker -/// waits for the cooldown duration before handling the next queue item. There -/// is no exponential backoff; failed requests are retried after the same -/// cooldown period. +/// # Errors /// -/// # Parameters -/// - `config`: shared daemon configuration. -/// - `rx`: receiver half of the queue channel. -/// - `octocrab`: authenticated GitHub client. +/// Returns errors from queue operations, deserialisation, or GitHub client failures. /// -/// # Errors -/// Propagates I/O and serialization errors from queue operations and any error -/// returned by the GitHub client. +/// # Examples +/// +/// ```no_run +/// use std::sync::Arc; +/// # use comenqd::{Config, run_worker}; +/// # use yaque::Receiver; +/// # use octocrab::Octocrab; +/// # async fn example() -> anyhow::Result<()> { +/// let config = Arc::new(Config::default()); +/// let rx: Receiver = /* obtain from yaque */ unimplemented!(); +/// let octocrab = Arc::new(Octocrab::builder().build()?); +/// run_worker(config, rx, octocrab).await?; +/// # Ok(()) +/// # } +/// ``` pub async fn run_worker( config: Arc, mut rx: Receiver, From 9402c47cb43c1b7a128ab3a6a2d3ab7c8cc8940d Mon Sep 17 00:00:00 2001 From: Leynos Date: Fri, 1 Aug 2025 12:39:01 +0100 Subject: [PATCH 2/2] Remove examples from non-public functions --- crates/comenqd/src/daemon.rs | 35 +---------------------------------- 1 file changed, 1 insertion(+), 34 deletions(-) diff --git a/crates/comenqd/src/daemon.rs b/crates/comenqd/src/daemon.rs index 423e4e7..0f479d4 100644 --- a/crates/comenqd/src/daemon.rs +++ b/crates/comenqd/src/daemon.rs @@ -40,12 +40,6 @@ enum PostCommentError { /// # Returns /// /// Returns an `Octocrab` client instance on success, or an error if the client could not be built. -/// -/// # Examples -/// -/// ```no_run -/// let octocrab = build_octocrab("ghp_exampletoken123")?; -/// ``` fn build_octocrab(token: &str) -> Result { Ok(Octocrab::builder() .personal_token(token.to_string()) @@ -62,15 +56,6 @@ fn prepare_listener(path: &Path) -> Result { } /// Asynchronously creates the queue directory and all necessary parent directories if they do not exist. -/// -/// # Examples -/// -/// ```no_run -/// use std::path::Path; -/// # tokio_test::block_on(async { -/// ensure_queue_dir(Path::new("/tmp/comenqd-queue")).await.unwrap(); -/// # }); -/// ``` async fn ensure_queue_dir(path: &Path) -> Result<()> { fs::create_dir_all(path).await?; Ok(()) @@ -81,24 +66,6 @@ async fn ensure_queue_dir(path: &Path) -> Result<()> { /// Returns `Ok(())` if the comment is successfully posted. If the GitHub API returns an error, /// returns `PostCommentError::Api`. If the operation does not complete within 10 seconds, /// returns `PostCommentError::Timeout`. -/// -/// # Examples -/// -/// ```no_run -/// # use comenqd::{post_comment, CommentRequest, PostCommentError}; -/// # use octocrab::Octocrab; -/// # async fn example() -> Result<(), PostCommentError> { -/// let octocrab = Octocrab::builder().personal_token("token").build().unwrap(); -/// let request = CommentRequest { -/// owner: "owner".to_string(), -/// repo: "repo".to_string(), -/// pr_number: 1, -/// body: "Test comment".to_string(), -/// }; -/// post_comment(&octocrab, &request).await?; -/// # Ok(()) -/// # } -/// ``` async fn post_comment( octocrab: &Octocrab, request: &CommentRequest, @@ -130,7 +97,7 @@ async fn post_comment( /// - or if the sender fails while awaiting shutdown. /// /// # Examples -/// ```no_run +/// ```rust,no_run /// use yaque::channel; /// use tokio::sync::mpsc; /// # async fn docs() -> anyhow::Result<()> {