docs: flow examples polish (#224)

docs/guides/flow/examples/01-local-environment.md

@@ -166,7 +166,8 @@ Suite result: ok. 2 passed; 0 failed; 0 skipped; finished in 986.20ms (4.16ms CP
 ## Next steps
 
 Congratulations! Your environment is now configured, and you are prepared to start building. Explore the guides section
-to discover various Flow features available for integration.
+to discover various Flow features available for integration. Remember to include all contracts (`.sol` files) in
+the`src` folder and their corresponding tests in the `test` folder.
 
 As far as Foundry is concerned, there is much more to uncover. If you want to learn more about it, check out the
 [Foundry Book](https://book.getfoundry.sh/), which contains numerous examples and tutorials. A deep understanding of

docs/guides/flow/examples/02-calculate-rps.mdx

@@ -1,31 +1,30 @@
 ---
 id: "flow-calculate-rps"
 sidebar_position: 2
-title: "Calculate Rate Per Second"
+title: "Calculate Rate per Second"
 ---
 
 import AdmonitionSimpleCode from "@site/docs/snippets/AdmonitionSimpleCode.mdx";
 
-# Calculate Rate Per Second
+This guide explains how to calculate the rate per second when creating a Flow stream. It is the most important step in
+setting up a stream since the rate per second is a key parameter in the stream's configuration.
 
-This guide explains how to calculate the value of rate per second to use in creating a Flow stream. It is the most
-important step in setting up a stream, since the rate per second is a key parameter in the protocol to track debt.
-
-It is assumed that you have already gone through the [Protocol Concepts](/concepts/streaming) and the
+We assume that you have already gone through the [Protocol Concepts](/concepts/streaming) and the
 [Flow Overview](/concepts/flow/overview) sections.
 
 <AdmonitionSimpleCode />
 
 The rate per second is the amount of tokens streamed in one second. It is represented as a fixed-point number with 18
-decimals, specifically as a type `UD21x18` from `PRBMath` library, which in Solidity is a type `uint128`.
+decimals, specifically as a `UD21x18` type from the `PRBMath` library. The underlying native Solidity type associated
+with `UD21x18` is `uint128`.
 
 Depending on how you receive payments, you have to calculate the rate per second and scale its value to 18 decimals
 format as below:
 
 1. Based on a duration, e.g., 3 months
-2. Between two fixed points in time, e.g., January 1, 2025, to April 1, 2025
+2. Between two points in time, e.g., January 1, 2025 to April, 1 2025
 
-The calculation method remains the same for both cases.
+The calculation method is the same in either case.
 
 ## Set up a library
 
@@ -48,7 +47,7 @@ Declare a library that can be used in other contracts:
 library FlowUtilities {}
 ```
 
-## Calculate the Rate Per Second on a Duration
+## Calculate the rate per second on a duration
 
 Define a function called `ratePerSecondWithDuration` that takes the following parameters and the returned value:
 
@@ -66,7 +65,7 @@ function ratePerSecondWithDuration(
 }
 ```
 
-First, retrieve the token's decimals, as not all tokens use the 18-decimal standard:
+First, retrieve the token's decimals. Note that not all ERC-20 tokens use the 18-decimal standard.
 
 ```solidity
 uint8 decimals = IERC20Metadata(token).decimals();
@@ -92,10 +91,9 @@ Then, multiply the amount by the scale factor and divide it by the duration:
 return ud21x18((amount * scaleFactor) / duration);
 ```
 
-## Calculate the Rate Per Second on Timestamps
+## Calculate the rate per second on timestamps
 
-The difference here is that we will have two time parameters, a start and an end time, instead of a duration. Let's
-define the function:
+Here, there are two time parameters, a start and an end time, instead of a duration. Let's define the function:
 
 ```solidity
 function ratePerSecondForTimestamps(
@@ -112,7 +110,7 @@ function ratePerSecondForTimestamps(
 }
 ```
 
-The first step would be now to calculate the duration between the two timestamps:
+The first step is to calculate the duration between the two timestamps:
 
 ```solidity
 uint40 duration = end - start;
@@ -132,9 +130,9 @@ uint128 scaleFactor = uint128(10 ** (18 - decimals));
 ratePerSecond = ud21x18((scaleFactor * amount) / duration);
 ```
 
-## Additional Utilities
+## Additional utilities
 
-To calculate earnings for specific durations from an existing stream, use the following functions:
+To calculate earnings for specific durations from an existing stream, you can use the following functions:
 
 ```solidity
 function calculateAmountStreamedPerWeek(UD21x18 ratePerSecond) internal pure returns (uint128 amountPerWeek) {

docs/guides/flow/examples/03-create-stream.mdx

@@ -9,10 +9,12 @@ import FlowDeployment from "@site/docs/snippets/FlowDeployment.mdx";
 
 # Create a Flow stream
 
-A Flow stream has no end date, which means it will continue to accumulate debt even if no funds are deposited. In this
-guide, we will show you how you can create a Flow stream using Solidity.
+In this guide, we will show you how you can create a Flow stream using Solidity.
 
-This guide assumes that you have already gone through the [Calculate Rate Per Second](./02-calculate-rps.mdx) section.
+It is important to note that A Flow stream has no end date, which means it will continue to accumulate debt even if no
+funds are deposited.
+
+This guide assumes that you have already gone through the [Calculate Rate per Second](./02-calculate-rps.mdx) section.
 
 <AdmonitionSimpleCode />
 
@@ -50,7 +52,7 @@ We will declare two functions, based on the amount desired to stream over a peri
 
 ## Define a function
 
-Define a function to stream a salary of 1,000 USDC per month, call it `createStream_1K_PerMonth` which returns the newly
+Define a function to stream a salary of 1000 USDC per month, call it `createStream_1K_PerMonth` which returns the newly
 created stream ID:
 
 ```solidity

docs/guides/flow/examples/04-stream-management.mdx

@@ -9,10 +9,10 @@ import FlowDeployment from "@site/docs/snippets/FlowDeployment.mdx";
 
 # Managing a Stream
 
-This section will guide you through different functions of Flow and how to interact with them. Before diving in, please
-note the following:
+This section will guide you through the different functions of Flow and how to interact with them. Before diving in,
+please note the following:
 
-1. We assume you are already familiar with [creating a stream](./03-create-stream.mdx).
+1. We assume you are already familiar with [creating Flow streams](./03-create-stream.mdx).
 2. We also assume that the stream management contract is authorized to invoke each respective function. To learn more
    about access control in Flow, see the [Access Control](/reference/flow/access-control) guide.
 
@@ -35,7 +35,7 @@ import { ud60x18 } from "@prb/math/src/UD60x18.sol";
 import { Broker, ISablierFlow } from "@sablier/flow/src/interfaces/ISablierFlow.sol";
 ```
 
-Declare the contract and add Flow address as a constant:
+Declare the contract and add the Flow address as a constant:
 
 ```solidity
 contract FlowStreamManager {
@@ -47,9 +47,15 @@ contract FlowStreamManager {
 
 ## Deposit
 
-Deposit into streams means adding tokens to the stream, which will then be distributed to the recipient based on the
+Depositing into streams means adding tokens to the stream, which will then be distributed to the recipient based on the
 value of rate per second.
 
+:::info
+
+A deposit is also referred to as a top-up.
+
+:::
+
 There are three deposit functions:
 
 1. [`deposit`](/reference/flow/contracts/contract.SablierFlow#deposit): deposits an amount of tokens.
@@ -83,12 +89,12 @@ function depositViaBroker(uint256 streamId) external {
 ## Withdraw
 
 The recipient of a stream can withdraw any amount, not exceeding the withdrawable amount. The recipient also has the
-option to withdraw the tokens to an alternate address of his choice.
+option to withdraw the tokens to an alternate address of their choice.
 
 There are two withdrawal functions:
 
 1. [`withdraw`](/reference/flow/contracts/contract.SablierFlow#withdraw): withdraws an amount of tokens not exceeding
-   withdrawable amount.
+   the withdrawable amount.
 2. [`withdrawMax`](/reference/flow/contracts/contract.SablierFlow#withdrawmax): withdraws the entire withdrawable amount
    of tokens.
 
@@ -102,9 +108,9 @@ function withdrawMax(uint256 streamId) external {
 }
 ```
 
-## Adjust Rate Per Second
+## Adjust Rate per Second
 
-Adjusting the rate per second means changing the amount of tokens to be streamed each second.
+Adjusting the rate per second means changing the amount of tokens that is streamed each second.
 
 ```solidity
 function adjustRatePerSecond(uint256 streamId) external {
@@ -114,7 +120,7 @@ function adjustRatePerSecond(uint256 streamId) external {
 
 ## Pause
 
-Pausing a stream means setting the rate per second to zero, which means no more streaming
+Pausing a stream means setting the rate per second to zero, which means no more streaming.
 
 ```solidity
 function pause(uint256 streamId) external {
@@ -144,9 +150,9 @@ function restartAndDeposit(uint256 streamId) external {
 
 There are three refund functions:
 
-1. [`refund`](/reference/flow/contracts/contract.SablierFlow#refund): refunds an amount of tokens not exceeding he
+1. [`refund`](/reference/flow/contracts/contract.SablierFlow#refund): refunds an amount of tokens not exceeding the
    refundable amount.
-2. [`refundAndPause`](/reference/flow/contracts/contract.SablierFlow#refundandpause): refunds an amount of tokens and
+2. [`refundAndPause`](/reference/flow/contracts/contract.SablierFlow#refundandpause): refunds an amount of tokens, and
    then pauses the stream.
 3. [`refundMax`](/reference/flow/contracts/contract.SablierFlow#refundmax): refunds the entire refundable amount of
    tokens.
@@ -167,8 +173,8 @@ function refundMax(uint256 streamId) external {
 
 ## Void
 
-Voiding a stream means stopping it forever from streaming any token. This is slightly different from pausing a stream
-because it also sets stream's uncovered debt to zero.
+Voiding a stream means permanently stopping it from streaming any tokens. This is slightly different from pausing a
+stream because it also sets the stream's uncovered debt to zero.
 
 ```solidity
 function void(uint256 streamId) external {

docs/guides/flow/examples/05-batchable.mdx

@@ -7,9 +7,9 @@ title: "Batching Functions"
 import AdmonitionSimpleCode from "@site/docs/snippets/AdmonitionSimpleCode.mdx";
 import FlowDeployment from "@site/docs/snippets/FlowDeployment.mdx";
 
-A unique feature of the Sablier Flow contract is its ability to batch multiple function calls into a single transaction.
-This functionality is made possible by the [`Batch`](/reference/flow/contracts/abstracts/abstract.Batch) contract,
-inherited by `SablierFlow`. With this, you can efficiently execute multiple functions in a single transaction.
+A neat feature of Sablier Flow is the ability to batch multiple function calls into a single transaction. This is made
+possible by the [`Batch`](/reference/flow/contracts/abstracts/abstract.Batch) contract, which is inherited by
+`SablierFlow`. With this, you can efficiently batch multiple function calls in a single transaction.
 
 <AdmonitionSimpleCode />
 
@@ -42,12 +42,12 @@ contract FlowBatchable {
 
 <FlowDeployment />
 
-## Create Multiple Streams
+## Create multiple streams
 
 One of the most useful features achieved by `batch` is the ability to create multiple streams in a single transaction.
 Let's focus on it in this example.
 
-Define a function that would create multiple streams in a single transaction and returns their respective stream IDs:
+Define a function that creates multiple streams and returns their respective stream IDs:
 
 ```solidity
 function createMultiple() external returns (uint256[] memory streamIds) {