Repository: apple/swift-nio
File: Sources/NIOCore/ByteBuffer-core.swift (Swift)

Code before:

/// `ByteBuffer` stores contiguously allocated raw bytes. It is a random and sequential accessible sequence of zero or
/// more bytes (octets).
///
/// ### Allocation
/// Use `allocator.buffer(capacity: desiredCapacity)` to allocate a new `ByteBuffer`.
///
/// ### Basic usage
/// A variety of types can be read/written from/to a `ByteBuffer`. Using Swift's `extension` mechanism you can easily
/// create `ByteBuffer` support for your own data types. Out of the box, `ByteBuffer` supports for example the following
/// types (non-exhaustive list):
///
///  - `String`/`StaticString`
///  - Swift's various (unsigned) integer types
///  - `Foundation`'s `Data`
///  - `[UInt8]` and generally any `Collection` of `UInt8`
///
/// **The best and easiest way to read and convert `ByteBuffer` into a `String`,  `Array<UInt8>`, or `Data` is by
/// passing the buffer to an initializer**.
///
/// Example:
///
///     let buf = ...
///     let myString = String(buffer:buf)
///
/// `ByteBuffer` provides APIs for reading it's contents either sequencially (`read*` methods) or randomly (`get*`
/// methods). All `ByteBuffer` methods that don't contain the word 'unsafe' will only allow you to access the readable
/// bytes of the butter, i.e. `readerIndex ..< writerIndex`.
///
/// If you need to loop over all the bytes in the buffer, you can use the `Collection` conformance with ``readableBytesView``:
///
///     for byte in buffer.readableBytesView {
///         print(byte)
///     }
///
/// If you need to process the whole buffer front to back, it's recommended that you use sequential `read*` methods:
///
///     while buffer.readableBytes > 0 {
///         let chunk = buffer.readBytes(length: min(chunkSize, buffer.readableBytes)
///         if let chunk {
///             // work with the chunk of data
///         } else {
///             // fallback in case of buffer read error.
///         }
///     }
///
/// ### Random Access
/// For every supported type `ByteBuffer` usually contains two methods for random access:
///
///  1. `get<Type>(at: Int, length: Int)` where `<type>` is for example `String`, `Data`, `Bytes` (for `[UInt8]`)
///  2. `set<Type>(at: Int)`

Review comment (suggestion):
```suggestion
/// `ByteBuffer` provides APIs for reading its contents either sequentially (`read*` methods) or randomly (`get*`
```

Code after:

/// `ByteBuffer` stores contiguously allocated raw bytes. It is a random and sequential accessible sequence of zero or
/// more bytes (octets).
///
/// ### Allocation
/// Use `allocator.buffer(capacity: desiredCapacity)` to allocate a new `ByteBuffer`.
///
/// ### Basic usage
/// A variety of types can be read/written from/to a `ByteBuffer`. Using Swift's `extension` mechanism you can easily
/// create `ByteBuffer` support for your own data types. Out of the box, `ByteBuffer` supports for example the following
/// types (non-exhaustive list):
///
///  - `String`/`StaticString`
///  - Swift's various (unsigned) integer types
///  - `Foundation`'s `Data`
///  - `[UInt8]` and generally any `Collection` of `UInt8`
///
/// The best and easiest way to read and convert ``ByteBuffer`` into a `String`,  `Array<UInt8>`, or `Data` is by
/// passing the buffer to an initializer.
///
/// Example:
///
///     let buf = ...
///     let myString = String(buffer: buf)
///
/// `ByteBuffer` provides APIs for reading its contents either sequentially (`read*` methods) or randomly (`get*`
/// methods). All `ByteBuffer` methods that don't contain the word 'unsafe' will only allow you to access the readable
/// bytes of the buffer, i.e. `readerIndex ..< writerIndex`.
///
/// If you need to loop over all the bytes in the buffer, you can use the `Collection` conformance with ``readableBytesView``:
///
///     for byte in buffer.readableBytesView {
///         print(byte)
///     }
///
/// If you need to process the whole buffer front to back, it's recommended that you use sequential `read*` methods:
///
///     while buffer.readableBytes > 0 {
///         if let chunk = buffer.readBytes(length: min(chunkSize, buffer.readableBytes) {
///             // work with the chunk of data
///         } else {
///             // fallback in case of buffer read error.
///         }
///     }
///
/// ### Random Access
/// For every supported type `ByteBuffer` usually contains two methods for random access:
///
///  1. `get<Type>(at: Int, length: Int)` where `<type>` is for example `String`, `Data`, `Bytes` (for `[UInt8]`)
///  2. `set<Type>(at: Int)`
///