Complete documentation

Author: tsolomko

Sources/BitReader.swift

@@ -5,38 +5,53 @@
 
 import Foundation
 
+/// A type that contains functions for reading `Data` bit-by-bit and byte-by-byte.
 public protocol BitReader: class {
 
+    /// True, if reader's BIT pointer is aligned with the BYTE border.
     var isAligned: Bool { get }
 
+    /// Creates an instance for reading `data`.
     init(data: Data)
 
+    /// Reads bit and returns it, advancing by one BIT position.
     func bit() -> UInt8
 
+    /// Reads `count` bits and returns them as an array of `UInt8`, advancing by `count` BIT positions.
     func bits(count: Int) -> [UInt8]
 
+    /// Reads `count` bits and returns them as a `Int` number, advancing by `count` BIT positions.
     func int(fromBits count: Int) -> Int
 
-    // TODO: Describe, that it doesn't check for the end.
+    /// Aligns reader's BIT pointer to the BYTE border, i.e. moves BIT pointer to the first BIT of the next BYTE.
     func align()
 
     // MARK: ByteReader's methods.
-    // TODO: Describe preconditions.
 
+    /// Reads byte and returns it, advancing by one BYTE position.
     func byte() -> UInt8
 
+    /// Reads `count` bytes and returns them as an array of `UInt8`, advancing by `count` BYTE positions.
     func bytes(count: Int) -> [UInt8]
 
+    /// Reads 8 bytes and returns them as a `UInt64` number, advancing by 8 BYTE positions.
     func uint64() -> UInt64
 
+    /// Reads 4 bytes and returns them as a `UInt32` number, advancing by 4 BYTE positions.
     func uint32() -> UInt32
 
+    /// Reads 2 bytes and returns them as a `UInt16` number, advancing by 2 BYTE positions.
     func uint16() -> UInt16
 
 }
 
 extension BitReader {
 
+    /**
+     Reads `count` bits and returns them as an array of `UInt8`, advancing by `count` BIT positions.
+
+     - Warning: Doesn't check if there is any data left.
+     */
     public func bits(count: Int) -> [UInt8] {
         guard count > 0
             else { return [] }

Sources/BitWriter.swift

@@ -5,31 +5,41 @@
 
 import Foundation
 
+/// A type that contains functions for writing `Data` bit-by-bit (and byte-by-byte).
 public protocol BitWriter {
 
+    /// Data which contains writer's output (the last byte in progress is not included).
     var data: Data { get }
 
-    init()
-
+    /// True, if writer's BIT pointer is aligned with the BYTE border.
     var isAligned: Bool { get }
 
+    /// Creates an instance for writing.
+    init()
+
+    /// Writes `bit`, advancing by one BIT position.
     func write(bit: UInt8)
 
+    /// Writes `bits`, advancing by `bits.count` BIT positions.
     func write(bits: [UInt8])
 
-    // TODO: Describe, what will happen if `bitsCount` is smaller than actual amount of `number`'s bits.
-    // TODO: Describe, that `number` is processed in the same order as `BitWriter`'s.
+    /// Writes `number`, using and advancing by `bitsCount` BIT positions.
     func write(number: Int, bitsCount: Int)
 
+    /// Writes `byte`, advancing by one BYTE position.
     func append(byte: UInt8)
 
-    // TODO: Describe, that it doesn't check if it actually needs to align.
+    /**
+     Aligns writer's BIT pointer to the BYTE border, i.e. moves BIT pointer to the first BIT of the next BYTE,
+     filling all skipped BIT positions with zeros.
+     */
     func align()
 
 }
 
 extension BitWriter {
 
+    /// Writes `bits`, advancing by `bits.count` BIT positions.
     public func write(bits: [UInt8]) {
         for bit in bits {
             self.write(bit: bit)

Sources/ByteReader.swift

@@ -37,7 +37,8 @@ public class ByteReader {
     /**
      Reads byte and returns it, advancing by one position.
 
-     - Warning: Doesn't check for potential out of bounds error, i.e. doesn't check if `isFinished` is true.
+     - Warning: Doesn't check if there is any data left. It is advisable to use `isFinished` BEFORE calling this method
+     to check if the end is reached.
      */
     public func byte() -> UInt8 {
         self.offset += 1
@@ -47,8 +48,8 @@ public class ByteReader {
     /**
      Reads `count` bytes and returns them as an array of `UInt8`, advancing by `count` positions.
 
-     - Warning: Doesn't check for potential out of bounds errors, i.e. doesn't check if `isFinished` will be true
-     at any point during the reading of these bytes.
+     - Warning: Doesn't check if there is any data left. It is advisable to use `isFinished` BEFORE calling this method
+     to check if the end is reached.
      */
     public func bytes(count: Int) -> [UInt8] {
         let result = self.data[self.offset..<self.offset + count].toArray(type: UInt8.self, count: count)
@@ -59,8 +60,8 @@ public class ByteReader {
     /**
      Reads 8 bytes and returns them as a `UInt64` number, advancing by 8 positions.
 
-     - Warning: Doesn't check for potential out of bounds errors, i.e. doesn't check if `isFinished` will be true
-     at any point during the reading of this number.
+     - Warning: Doesn't check if there is any data left. It is advisable to use `isFinished` BEFORE calling this method
+     to check if the end is reached.
      */
     public func uint64() -> UInt64 {
         let result = self.data[self.offset..<self.offset + 8].to(type: UInt64.self)
@@ -71,8 +72,8 @@ public class ByteReader {
     /**
      Reads 4 bytes and returns them as a `UInt32` number, advancing by 4 positions.
 
-     - Warning: Doesn't check for potential out of bounds errors, i.e. doesn't check if `isFinished` will be true
-     at any point during the reading of this number.
+     - Warning: Doesn't check if there is any data left. It is advisable to use `isFinished` BEFORE calling this method
+     to check if the end is reached.
      */
     public func uint32() -> UInt32 {
         let result = self.data[self.offset..<self.offset + 4].to(type: UInt32.self)
@@ -83,8 +84,8 @@ public class ByteReader {
     /**
      Reads 2 bytes and returns them as a `UInt16` number, advancing by 2 positions.
 
-     - Warning: Doesn't check for potential out of bounds errors, i.e. doesn't check if `isFinished` will be true
-     at any point during the reading of this number.
+     - Warning: Doesn't check if there is any data left. It is advisable to use `isFinished` BEFORE calling this method
+     to check if the end is reached.
      */
     public func uint16() -> UInt16 {
         let result = self.data[self.offset..<self.offset + 2].to(type: UInt16.self)

Sources/LsbBitReader.swift

@@ -5,14 +5,25 @@
 
 import Foundation
 
+/**
+ A type that contains functions for reading `Data` bit-by-bit and byte-by-byte,
+ assuming "LSB 0" bit numbering scheme.
+ */
 public final class LsbBitReader: ByteReader, BitReader {
 
     private var bitMask: UInt8 = 1
 
+    /// True, if reader's BIT pointer is aligned with the BYTE border.
     public var isAligned: Bool {
         return self.bitMask == 1
     }
 
+    /**
+     Reads bit and returns it, advancing by one BIT position.
+
+     - Warning: Doesn't check if there is any data left. It is advisable to use `isFinished` BEFORE calling this method
+     to check if the end is reached.
+     */
     public func bit() -> UInt8 {
         let bit: UInt8 = self.data[self.offset] & self.bitMask > 0 ? 1 : 0
 
@@ -26,6 +37,12 @@ public final class LsbBitReader: ByteReader, BitReader {
         return bit
     }
 
+    /**
+     Reads `count` bits and returns them as a `Int` number, advancing by `count` BIT positions.
+
+     - Warning: Doesn't check if there is any data left. It is advisable to use `isFinished` BEFORE calling this method
+     to check if the end is reached.
+     */
     public func int(fromBits count: Int) -> Int {
         guard count > 0
             else { return 0 }
@@ -48,6 +65,13 @@ public final class LsbBitReader: ByteReader, BitReader {
         return result
     }
 
+    /**
+     Aligns reader's BIT pointer to the BYTE border, i.e. moves BIT pointer to the first BIT of the next BYTE.
+
+     - Note: If reader is already aligned, then does nothing.
+     - Warning: Doesn't check if there is any data left. It is advisable to use `isFinished` AFTER calling this method
+     to check if the end was reached.
+     */
     public func align() {
         guard self.bitMask != 1
             else { return }
@@ -58,26 +82,61 @@ public final class LsbBitReader: ByteReader, BitReader {
 
     // MARK: ByteReader's methods.
 
+    /**
+     Reads byte and returns it, advancing by one BYTE position.
+
+     - Warning: Doesn't check if there is any data left. It is advisable to use `isFinished` BEFORE calling this method
+     to check if the end is reached.
+     - Precondition: Reader MUST be aligned.
+     */
     public override func byte() -> UInt8 {
         precondition(isAligned, "BitReader is not aligned.")
         return super.byte()
     }
 
+    /**
+     Reads `count` bytes and returns them as an array of `UInt8`, advancing by `count` BYTE positions.
+
+     - Warning: Doesn't check if there is any data left. It is advisable to use `isFinished` BEFORE calling this method
+     to check if the end is reached.
+     - Precondition: Reader MUST be aligned.
+     */
     public override func bytes(count: Int) -> [UInt8] {
         precondition(isAligned, "BitReader is not aligned.")
         return super.bytes(count: count)
     }
 
+    /**
+     Reads 8 bytes and returns them as a `UInt64` number, advancing by 8 BYTE positions.
+
+     - Warning: Doesn't check if there is any data left. It is advisable to use `isFinished` BEFORE calling this method
+     to check if the end is reached.
+     - Precondition: Reader MUST be aligned.
+     */
     public override func uint64() -> UInt64 {
         precondition(isAligned, "BitReader is not aligned.")
         return super.uint64()
     }
 
+    /**
+     Reads 4 bytes and returns them as a `UInt32` number, advancing by 4 BYTE positions.
+
+     - Warning: Doesn't check if there is any data left. It is advisable to use `isFinished` BEFORE calling this method
+     to check if the end is reached.
+     - Precondition: Reader MUST be aligned.
+     */
     public override func uint32() -> UInt32 {
         precondition(isAligned, "BitReader is not aligned.")
         return super.uint32()
     }
 
+    /**
+     Reads 2 bytes and returns them as a `UInt16` number, advancing by 2 BYTE positions.
+
+     - Warning: Doesn't check if there is any data left. It is advisable to use `isFinished` BEFORE calling this method
+     to check if the end is reached.
+     - Precondition: Reader MUST be aligned.
+     */
     public override func uint16() -> UInt16 {
         precondition(isAligned, "BitReader is not aligned.")
         return super.uint16()

Sources/LsbBitWriter.swift

@@ -5,19 +5,27 @@
 
 import Foundation
 
+/**
+ A type that contains functions for writing `Data` bit-by-bit (and byte-by-byte),
+ assuming "LSB 0" bit numbering scheme.
+ */
 public final class LsbBitWriter: BitWriter {
 
+    /// Data which contains writer's output (the last byte in progress is not included).
     public private(set) var data: Data = Data()
 
     private var bitMask: UInt8 = 1
     private var currentByte: UInt8 = 0
 
+    /// True, if writer's BIT pointer is aligned with the BYTE border.
     public var isAligned: Bool {
         return self.bitMask == 1
     }
 
+    /// Creates an instance for writing.
     public init() { }
 
+    /// Writes `bit`, advancing by one BIT position.
     public func write(bit: UInt8) {
         precondition(bit <= 1, "A bit must be either 0 or 1.")
 
@@ -32,6 +40,13 @@ public final class LsbBitWriter: BitWriter {
         }
     }
 
+    /**
+     Writes `number`, using and advancing by `bitsCount` BIT positions.
+
+     - Note: If `bitsCount` is smaller than the actual amount of `number`'s bits than the `number` will be truncated to
+     fit into `bitsCount` amount of bits.
+     - Note: Bits of `number` are processed using the same bit-numbering scheme as of the writer (i.e. "LSB 0").
+     */
     public func write(number: Int, bitsCount: Int) {
         var mask = 1
         for _ in 0..<bitsCount {
@@ -40,11 +55,22 @@ public final class LsbBitWriter: BitWriter {
         }
     }
 
+    /**
+     Writes `byte`, advancing by one BYTE position.
+
+     - Precondition: Writer MUST be aligned.
+     */
     public func append(byte: UInt8) {
         precondition(isAligned, "BitWriter is not aligned.")
         self.data.append(byte)
     }
 
+    /**
+     Aligns writer's BIT pointer to the BYTE border, i.e. moves BIT pointer to the first BIT of the next BYTE,
+     filling all skipped BIT positions with zeros.
+
+     - Note: If writer is already aligned, then does nothing.
+     */
     public func align() {
         self.data.append(self.currentByte)
         self.currentByte = 0