From da907c2ec34aba56cbcd865c639dd8bcc9bad264 Mon Sep 17 00:00:00 2001 From: Wilfred Hughes Date: Tue, 13 Aug 2024 15:20:09 -0700 Subject: [PATCH] docs: Add a doc comment for OpQueue Add an explanatory sentence and some sample code to help readers understand why this struct exists. --- crates/rust-analyzer/src/op_queue.rs | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/crates/rust-analyzer/src/op_queue.rs b/crates/rust-analyzer/src/op_queue.rs index 99f9e9829c..eab9733872 100644 --- a/crates/rust-analyzer/src/op_queue.rs +++ b/crates/rust-analyzer/src/op_queue.rs @@ -3,6 +3,26 @@ pub(crate) type Cause = String; +/// A single-item queue that allows callers to request an operation to +/// be performed later. +/// +/// ``` +/// let queue = OpQueue::default(); +/// +/// // Request work to be done. +/// queue.request_op("user pushed a button", ()); +/// +/// // In a later iteration of the server loop, we start the work. +/// if let Some((_cause, ())) = queue.should_start_op() { +/// dbg!("Some slow operation here"); +/// } +/// +/// // In an even later iteration of the server loop, we can see that the work +/// // was completed. +/// if !queue.op_in_progress() { +/// dbg!("Work has been done!"); +/// } +/// ``` #[derive(Debug)] pub(crate) struct OpQueue { op_requested: Option<(Cause, Args)>,