Repository: tokio-rs/tokio
File: tokio/src/sync/semaphore.rs (Rust)

Code before:
/// use std::io::Result;
/// use tokio::fs::File;
/// use tokio::sync::Semaphore;
/// use tokio::io::AsyncWriteExt;
///
/// static PERMITS: Semaphore = Semaphore::const_new(100);
///
/// async fn write_to_file(message: &[u8]) -> Result<()> {
///     let _permit = PERMITS.acquire().await.unwrap();
///     let mut buffer = File::create("example.txt").await?;
///     buffer.write_all(message).await?;
///     Ok(()) // Permit goes out of scope here, and is available again for acquisition
/// }
/// ```
///
/// ## Limit the number of outgoing requests being sent at the same time
///
/// In some scenarios, it might be required to limit the number of outgoing
/// requests being sent in parallel. This could be due to limits of a consumed
/// API or the network resources of the system the application is running on.
///
/// This example uses an `Arc<Semaphore>` with 10 permits.
/// Each task spawned is given a reference to the semaphore by cloning the `Arc<Semaphore>`.
/// Before a task sends a request, it must acquire a permit from the semaphore by calling [`Semaphore::acquire`].
/// This ensures that at most 10 requests are sent in parallel at any given time.
/// After a task has sent a request, it drops the permit to allow other tasks to send requests.
///
/// ```
/// use std::sync::Arc;
/// use tokio::sync::Semaphore;
///
/// #[tokio::main]
/// async fn main() {
///     // Define maximum number of parallel requests.
///     let semaphore = Arc::new(Semaphore::new(10));
///     // Spawn many tasks that will send requests.
///     let mut jhs = Vec::new();
///     for task_id in 0..100 {
///         let semaphore = semaphore.clone();
///         let jh = tokio::spawn(async move {
///             // Acquire permit before sending request.
///             let _permit = semaphore.acquire().await.unwrap();
///             // Send the request.
///             let response = send_request(task_id).await;
///             // Drop the permit after the request has been sent.
///             drop(_permit);
///             // Handle response.
///             // ...
///         });
///         jhs.push(jh);
///     }

Review comment (suggestion):
This markdown has a newline after each sentence, but that's not how it will be rendered in the browser. Screenshot:

![image](https://github.com/tokio-rs/tokio/assets/928074/f894b46c-1041-4883-9881-8f5a7f1877c9)

I would prefer if you reflow these sentences so that each line goes as close as it can to a maximum of 80 characters per line, like you did in the previous paragraph.

Or if you intended for this to be a list, then add bullet points to make it into an actual list.

Code after:
/// use std::io::Result;
/// use tokio::fs::File;
/// use tokio::sync::Semaphore;
/// use tokio::io::AsyncWriteExt;
///
/// static PERMITS: Semaphore = Semaphore::const_new(100);
///
/// async fn write_to_file(message: &[u8]) -> Result<()> {
///     let _permit = PERMITS.acquire().await.unwrap();
///     let mut buffer = File::create("example.txt").await?;
///     buffer.write_all(message).await?;
///     Ok(()) // Permit goes out of scope here, and is available again for acquisition
/// }
/// ```
///
/// ## Limit the number of outgoing requests being sent at the same time
///
/// In some scenarios, it might be required to limit the number of outgoing
/// requests being sent in parallel. This could be due to limits of a consumed
/// API or the network resources of the system the application is running on.
///
/// This example uses an `Arc<Semaphore>` with 10 permits. Each task spawned is
/// given a reference to the semaphore by cloning the `Arc<Semaphore>`. Before
/// a task sends a request, it must acquire a permit from the semaphore by
/// calling [`Semaphore::acquire`]. This ensures that at most 10 requests are
/// sent in parallel at any given time. After a task has sent a request, it
/// drops the permit to allow other tasks to send requests.
///
/// ```
/// use std::sync::Arc;
/// use tokio::sync::Semaphore;
///
/// #[tokio::main]
/// async fn main() {
///     // Define maximum number of parallel requests.
///     let semaphore = Arc::new(Semaphore::new(10));
///     // Spawn many tasks that will send requests.
///     let mut jhs = Vec::new();
///     for task_id in 0..100 {
///         let semaphore = semaphore.clone();
///         let jh = tokio::spawn(async move {
///             // Acquire permit before sending request.
///             let _permit = semaphore.acquire().await.unwrap();
///             // Send the request.
///             let response = send_request(task_id).await;
///             // Drop the permit after the request has been sent.
///             drop(_permit);
///             // Handle response.
///             // ...
///
///             response