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

Code before:
///     let permit = PERMIT.acquire().await.unwrap();
///
///     // Do the same insert.
///     let (key, value) = ("name", 0);
///     DB.lock().await.insert(key, value);
///
///     // Update the existing value with a new one.
///     let new_value = 1;
///     DB.lock().await.update(key, new_value);
///
///     // Verify if the value has been updated correctly.
///     assert_eq!(DB.lock().await.get(key), new_value);
///
///     // Undo any modificattion.
///     DB.lock().await.delete(key);
///
///     // Drop permit, make possible waiting test to run.
///     drop(permit);
/// }
///
/// async fn test_others() {
///     // this test can run in parallel with test_insert and test_update.
///     // They have nothing to do with PERMIT.
/// }
/// # #[test]
/// # fn fake_test() {}
/// # #[tokio::main]
/// # async fn main() {
///   # test_insert().await;
///   # test_update().await;
///   # test_others().await;
/// # }
///
/// ```
///
/// ## Rate limiting using a token bucket
///
/// Many applications and systems have constraints on the rate at which certain
/// operations should occur. Exceeding this rate can result in suboptimal
/// performance or even errors.
///
/// This example implements rate limiting using a [token bucket]. A token bucket is a form of rate
/// limiting that doesn't kick in immediately, to allow for short bursts of incoming requests that
/// arrive at the same time.
///
/// With a token bucket, each incoming request consumes a token, and the tokens are refilled at a
/// certain rate that defines the rate limit. When a burst of requests arrives, tokens are
/// immediately given out until the bucket is empty. Once the bucket is empty, requests will have to
/// wait for new tokens to be added.
///
/// Unlike the example that limits how many requests can be handled at the same time, we do not add

Review comment (suggestion):
Please put this on the actual tests. The goal is to make `#[test]` show up as annotations on `test_insert` and `test_update`.

Code after:
///     // the test will wait if the permit is already acquired by other tests.
///     let permit = PERMIT.acquire().await.unwrap();
///
///     // Do the same insert.
///     let (key, value) = ("name", 0);
///     DB.insert(key, value).await;
///
///     // Update the existing value with a new one.
///     let new_value = 1;
///     DB.update(key, new_value).await;
///
///     // Verify that the value has been updated correctly.
///     assert_eq!(DB.get(key).await, new_value);
///
///     // Undo any modificattion.
///     DB.delete(key).await;
///
///     // Drop permit. This allows the other test to start running.
///     drop(permit);
/// }
///
/// #[tokio::test]
/// # async fn fake_test() {}
/// async fn test_others() {
///     // This test can run in parallel with test_insert and test_update,
///     // so it does not use PERMIT.
/// }
/// # #[tokio::main]
/// # async fn main() {
/// #   test_insert().await;
/// #   test_update().await;
/// #   test_others().await;
/// # }
/// ```
///
/// ## Rate limiting using a token bucket
///
/// Many applications and systems have constraints on the rate at which certain
/// operations should occur. Exceeding this rate can result in suboptimal
/// performance or even errors.
///
/// This example implements rate limiting using a [token bucket]. A token bucket is a form of rate
/// limiting that doesn't kick in immediately, to allow for short bursts of incoming requests that
/// arrive at the same time.
///
/// With a token bucket, each incoming request consumes a token, and the tokens are refilled at a
/// certain rate that defines the rate limit. When a burst of requests arrives, tokens are
/// immediately given out until the bucket is empty. Once the bucket is empty, requests will have to
/// wait for new tokens to be added.
///
/// Unlike the example that limits how many requests can be handled at the same time, we do not add