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

Code before:
    ///
    /// - note: This method will allocate if the underlying storage is referenced by another `ByteBuffer`. Even if an
    ///         allocation is necessary this will be cheaper as the copy of the storage is elided.
    ///
    /// - parameters:
    ///     - minimumCapacity: The minimum capacity that will be (re)allocated for this buffer
    @inlinable
    public mutating func clear(minimumCapacity: Int) {
        precondition(minimumCapacity >= 0, "Cannot have a minimum capacity < 0")
        precondition(minimumCapacity <= _Capacity.max, "Minimum capacity must be <= \(_Capacity.max)")

        let minimumCapacity = _Capacity(minimumCapacity)
        if !isKnownUniquelyReferenced(&self._storage) {
            self._storage = self._storage.allocateStorage(capacity: minimumCapacity)
        } else if minimumCapacity > self._storage.capacity {
            self._storage.reallocStorage(capacity: minimumCapacity)
        }
        self._slice = self._storage.fullSlice

        self._moveWriterIndex(to: 0)
        self._moveReaderIndex(to: 0)
    }
}

extension ByteBuffer: CustomStringConvertible, CustomDebugStringConvertible {
    /// A `String` describing this `ByteBuffer`.  For a `ByteBuffer` initialised with `hello world`
    /// the description would be the following:
    ///
    ///     [68656c6c6f20776f726c64](11 bytes)
    ///
    /// Buffers larger that 64 bytes will get truncated when printing out.
    /// The format of the description is not API.
    ///
    /// - returns: A description of this `ByteBuffer`.
    public var description: String {
        "[\(self.hexDump(format: .compact(maxBytes: 64)))](\(self.readableBytes) bytes)"
    }

    /// A `String` describing this `ByteBuffer`.  For a `ByteBuffer` initialised with `hello world`
    /// the description would be the following:
    ///
    ///     [68656c6c6f20776f726c64](11 bytes)
    ///
    /// Buffers larger that 64 bytes will get truncated when printing out.
    /// The format of the description is not API.
    ///
    /// - returns: A description of this `ByteBuffer`.
    public var debugDescription: String {
        "[\(self.hexDump(format: .compact(maxBytes: 64)))](\(self.readableBytes) bytes)"
    }
}

Review comment (suggestion):
```suggestion
    /// A `String` describing this `ByteBuffer` including length and the bytes it contains (partially).
    ///
    /// For a `ByteBuffer` initialised with `hello world`
```

Nit: The first line in the doc comments is special, it's the summary. That summary gets displayed by itself in many scenarios so we should aim for it to make sense without the rest of the doc comment.

Code after:
    ///
    /// - note: This method will allocate if the underlying storage is referenced by another `ByteBuffer`. Even if an
    ///         allocation is necessary this will be cheaper as the copy of the storage is elided.
    ///
    /// - parameters:
    ///     - minimumCapacity: The minimum capacity that will be (re)allocated for this buffer
    @inlinable
    public mutating func clear(minimumCapacity: Int) {
        precondition(minimumCapacity >= 0, "Cannot have a minimum capacity < 0")
        precondition(minimumCapacity <= _Capacity.max, "Minimum capacity must be <= \(_Capacity.max)")

        let minimumCapacity = _Capacity(minimumCapacity)
        if !isKnownUniquelyReferenced(&self._storage) {
            self._storage = self._storage.allocateStorage(capacity: minimumCapacity)
        } else if minimumCapacity > self._storage.capacity {
            self._storage.reallocStorage(capacity: minimumCapacity)
        }
        self._slice = self._storage.fullSlice

        self._moveWriterIndex(to: 0)
        self._moveReaderIndex(to: 0)
    }
}

extension ByteBuffer: CustomStringConvertible, CustomDebugStringConvertible {
    /// A `String` describing this `ByteBuffer` including length and the bytes it contains (partially).
    ///
    /// For a `ByteBuffer` initialised with `hello world` the description would be the following:
    ///
    ///     [68656c6c6f20776f726c64](11 bytes)
    ///
    /// Buffers larger that 64 bytes will get truncated when printing out.
    /// The format of the description is not API.
    ///
    /// - returns: A description of this `ByteBuffer`.
    public var description: String {
        "[\(self.hexDump(format: .compact(maxBytes: 64)))](\(self.readableBytes) bytes)"
    }

    /// A `String` describing this `ByteBuffer` including length and the bytes it contains (partially).
    ///
    /// For a `ByteBuffer` initialised with `hello world` the description would be the following:
    ///
    ///     [68656c6c6f20776f726c64](11 bytes)
    ///
    /// Buffers larger that 64 bytes will get truncated when printing out.
    /// The format of the description is not API.
    ///
    /// - returns: A description of this `ByteBuffer`.
    public var debugDescription: String {
        "[\(self.hexDump(format: .compact(maxBytes: 64)))](\(self.readableBytes) bytes)"