From ece6e1ed83a020585d9e85daebc7c088a270dacf Mon Sep 17 00:00:00 2001
From: "coderabbitai[bot]"
 <136622811+coderabbitai[bot]@users.noreply.github.com>
Date: Fri, 13 Jun 2025 18:20:30 +0000
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20docstrings=20to=20`codex/e?=
 =?UTF-8?q?nsure-minimum-of-one-worker-in-wireframeserver`?=
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/wireframe/pull/16#issuecomment-2970615031

The following files were modified:

* `src/extractor.rs`
* `src/middleware.rs`
* `src/server.rs`
---
 src/extractor.rs  | 13 +++++++++++++
 src/middleware.rs | 20 +++++++++++++++++++-
 src/server.rs     | 33 +++++++++++++++++++++++++++++++++
 3 files changed, 65 insertions(+), 1 deletion(-)

diff --git a/src/extractor.rs b/src/extractor.rs
index 3cd9767e..41f01e28 100644
--- a/src/extractor.rs
+++ b/src/extractor.rs
@@ -100,6 +100,19 @@ impl<T: Send + Sync> std::ops::Deref for SharedState<T> {
     /// let state = Arc::new(42);
     /// let shared = SharedState::new(state.clone());
     /// assert_eq!(*shared, 42);
+    /// Returns a reference to the inner shared state value.
+    ///
+    /// Allows transparent access to the wrapped state as if it were a reference to the underlying type.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::sync::Arc;
+    /// use wireframe::extractor::SharedState;
+    ///
+    /// let state = Arc::new(42);
+    /// let shared = SharedState::new(state);
+    /// assert_eq!(*shared, 42);
     /// ```
     fn deref(&self) -> &Self::Target {
         &self.0
diff --git a/src/middleware.rs b/src/middleware.rs
index 22153d2d..052f6424 100644
--- a/src/middleware.rs
+++ b/src/middleware.rs
@@ -22,6 +22,22 @@ where
 {
     /// Creates a new `Next` instance wrapping a reference to the given service.
     #[must_use]
+    /// Creates a new `Next` instance wrapping a reference to the given service.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use your_crate::{Next, Service, ServiceRequest};
+    /// # struct MyService;
+    /// # impl Service for MyService {
+    /// #     type Error = std::convert::Infallible;
+    /// #     async fn call(&self, _req: ServiceRequest) -> Result<super::ServiceResponse, Self::Error> {
+    /// #         Ok(super::ServiceResponse)
+    /// #     }
+    /// # }
+    /// let service = MyService;
+    /// let next = Next::new(&service);
+    /// ```
     pub fn new(service: &'a S) -> Self {
         Self { service }
     }
@@ -30,7 +46,9 @@ where
     ///
     /// # Errors
     ///
-    /// Returns an error from the wrapped service if handling the request fails.
+    /// Asynchronously invokes the wrapped service with the given request.
+    ///
+    /// Returns a response produced by the service, or an error if the service fails to handle the request.
     pub async fn call(&self, req: ServiceRequest) -> Result<ServiceResponse, S::Error> {
         self.service.call(req).await
     }
diff --git a/src/server.rs b/src/server.rs
index e34aa531..2dbf25f0 100644
--- a/src/server.rs
+++ b/src/server.rs
@@ -41,6 +41,19 @@ where
     ///
     /// let factory = || WireframeApp::new().unwrap();
     /// let server = WireframeServer::new(factory);
+    /// Creates a new `WireframeServer` with the provided factory closure.
+    ///
+    /// The server is initialised with a default worker count equal to the number of available CPU cores, or 1 if this cannot be determined. The TCP listener is unset and must be configured with `bind` before running the server.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the number of available CPUs cannot be determined and the fallback to 1 fails.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let server = WireframeServer::new(|| WireframeApp::default());
+    /// assert!(server.worker_count() >= 1);
     /// ```
     pub fn new(factory: F) -> Self {
         let workers = std::thread::available_parallelism().map_or(1, std::num::NonZeroUsize::get);
@@ -61,6 +74,18 @@ where
     /// let server = WireframeServer::new(factory).workers(4);
     /// ```
     #[must_use]
+    /// Sets the number of worker tasks to spawn, ensuring at least one worker is configured.
+    ///
+    /// Returns a new `WireframeServer` instance with the updated worker count. If `count` is less than 1, it defaults to 1.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let server = WireframeServer::new(factory).workers(4);
+    /// assert_eq!(server.worker_count(), 4);
+    /// let server = server.workers(0);
+    /// assert_eq!(server.worker_count(), 1);
+    /// ```
     pub fn workers(mut self, count: usize) -> Self {
         self.workers = count.max(1);
         self
@@ -69,6 +94,14 @@ where
     /// Get the configured worker count.
     #[inline]
     #[must_use]
+    /// Returns the configured number of worker tasks for the server.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let server = WireframeServer::new(factory);
+    /// assert!(server.worker_count() >= 1);
+    /// ```
     pub const fn worker_count(&self) -> usize {
         self.workers
     }