 ///  - `[UInt8]` and generally any `Collection` (& `ContiguousCollection`) of `UInt8`
 ///
 /// ### 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>: Type, at: Int)`
+///
+/// Example:
+///
+///     var buf = ...
+///     buf.set(string: "Hello World", at: 0)
+///     let helloWorld = buf.getString(at: 0, length: 11)
+///
+///     buf.set(integer: 17 as Int, at: 11)
+///     let seventeen: Int = buf.getInteger(at: 11)
+///
+/// If needed, `ByteBuffer` will automatically resize its storage to accomodate your `set` request.
+///
+/// ### Sequential Access
 /// `ByteBuffer` provides two properties which are indices into the `ByteBuffer` to support sequential access:
 ///  - `readerIndex`, the index of the next readable byte
 ///  - `writerIndex`, the index of the next byte to write
 ///
-/// 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>: Type, at: Int)`
-///
-/// Example:
-///
-///     var buf = ...
-///     buf.set(string: "Hello World", at: 0)
-///     let helloWorld = buf.getString(at: 0, length: 11)
-///
-///     buf.set(integer: 17 as Int, at: 11)
-///     let seventeen: Int = buf.getInteger(at: 11)
-///
-/// If needed, `ByteBuffer` will automatically resize its storage to accomodate your `set` request.
-///
-/// ### Sequential Access
 /// For every supported type `ByteBuffer` usually contains two methods for sequential access:
 ///
 ///  1. `read<type>(length: Int)` to read `length` bytes from the current `readerIndex` (and then advance the reader index by `length` bytes)

        return self._slice.count
    }

    /// Change the capacity to at least `newCapacity` bytes.
    ///
    /// - parameters:
    ///     - newCapacity: The desired minimum capacity.
    public mutating func changeCapacity(to newCapacity: Int) {
        precondition(newCapacity >= self.writerIndex,
                     "new capacity \(newCapacity) less than the writer index (\(self.writerIndex))")

/// more bytes (octets).
///
/// ### Allocation
/// Use `allocator.buffer(capacity: desiredCapacity)` to allocate a new `ByteBuffer`.
///
/// ### Supported types
/// A variety of types can be read/written from/to a `ByteBuffer`. Using Swift's `extension` mechanism you can easily
