Update docs of Lsb/MsbBitWriter, BitWriter protocol and its extension

Author: tsolomko

Sources/BitWriter.swift

@@ -5,57 +5,80 @@
 
 import Foundation
 
-/// A type that contains functions for writing `Data` bit-by-bit (and byte-by-byte).
+/// 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).
+    /// Data which contains the writer's output (the last byte, that is currently being written, is not included).
     var data: Data { get }
 
-    /// True, if writer's BIT pointer is aligned with the BYTE border.
+    /// True, if a bit pointer is aligned to a byte boundary.
     var isAligned: Bool { get }
 
-    /// Creates an instance for writing bits (and bytes).
+    /// Creates an instance for writing bits and bytes.
     init()
 
-    /// Writes `bit`, advancing by one BIT position.
+    /// Writes a `bit`, advancing by one bit position.
     func write(bit: UInt8)
 
-    /// Writes `bits`, advancing by `bits.count` BIT positions.
+    /// Writes `bits`, advancing by `bits.count` bit positions.
     func write(bits: [UInt8])
 
-    /// Writes `number`, using and advancing by `bitsCount` BIT positions.
+    /// Writes a `number` into `bitsCount` amount of bits, advancing by `bitsCount` bit positions.
     func write(number: Int, bitsCount: Int)
 
-    /// Writes signed `number`, using and advancing by `bitsCount` BIT positions.
+    /**
+     Writes a signed integer `number` into `bitsCount` amount of bits, advancing by `bitsCount` bit positions, while
+     using a `representation` as a method to represent the signed integer in a binary format.
+     */
     func write(signedNumber: Int, bitsCount: Int, representation: SignedNumberRepresentation)
 
-    /// Writes unsigned `number`, using and advancing by `bitsCount` BIT positions.
+    /// Writes an unsigned `number`, advancing by `bitsCount` bit positions.
     func write(unsignedNumber: UInt, bitsCount: Int)
 
-    /// Writes `byte`, advancing by one BYTE position.
+    /// Writes a `byte`, advancing by one byte position.
     func append(byte: UInt8)
 
     /**
-     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.
+     Aligns a bit pointer to a byte boundary, i.e. moves the 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, using the `write(bit:)` function.
     public func write(bits: [UInt8]) {
         for bit in bits {
             self.write(bit: bit)
         }
     }
 
+    /**
+     Converts a `number` into an `UInt` integer, and writes it into `bitsCount` amount of bits by using the
+     `write(unsignedNumber:bitsCount:)` function, advancing by `bitsCount` bit positions.
+
+     - Note: If the data is supposed to represent a signed integer (i.e. it is important to preserve the sign), it is
+     recommended to use the `write(signedNumber:bitsCount:representation:)` function.
+     - Precondition: Parameter `bitsCount` must be in the `0...Int.bitWidth` range.
+     */
     public func write(number: Int, bitsCount: Int) {
         precondition(0...Int.bitWidth ~= bitsCount)
         self.write(unsignedNumber: UInt(bitPattern: number), bitsCount: bitsCount)
     }
 
+    /**
+     Writes a signed integer `number` into `bitsCount` amount of bits, advancing by `bitsCount` bit positions, while
+     using a `representation` as a method to represent the signed integer in a binary format. This implementation uses
+     the `write(unsignedNumber:bitsCount:)` function in the final stage of writing.
+
+     The default value of `representation` is `SignedNumberRepresentation.twoComplementNegatives`.
+
+     - Precondition: The `signedNumber` must be representable within `bitsCount` bits using the `representation`, i.e.
+     it must be in the `representation.minRepresentableNumber...representation.maxRepresentableNumber` range.
+     - Precondition: For the `SignedNumberRepresentation.biased` representation, the `bias` must be non-negative.
+     */
     public func write(signedNumber: Int, bitsCount: Int, representation: SignedNumberRepresentation = .twoComplementNegatives) {
         precondition(signedNumber >= representation.minRepresentableNumber(bitsCount: bitsCount) &&
                         signedNumber <= representation.maxRepresentableNumber(bitsCount: bitsCount),

Sources/LsbBitWriter.swift

@@ -6,26 +6,29 @@
 import Foundation
 
 /**
- A type that contains functions for writing `Data` bit-by-bit (and byte-by-byte),
- assuming "LSB 0" bit numbering scheme.
+ A type that contains functions for writing `Data` bit-by-bit and byte-by-byte using "LSB 0" bit numbering scheme.
  */
 public final class LsbBitWriter: BitWriter {
 
-    /// Data which contains writer's output (the last byte in progress is not included).
+    /// Data which contains the writer's output (the last byte, that is currently being written, 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.
+    /// True, if a bit pointer is aligned to a byte boundary.
     public var isAligned: Bool {
         return self.bitMask == 1
     }
 
-    /// Creates an instance for writing bits (and bytes).
+    /// Creates an instance for writing bits and bytes.
     public init() { }
 
-    /// Writes `bit`, advancing by one BIT position.
+    /**
+     Writes a `bit`, advancing by one bit position.
+
+     - Precondition: The `bit` must be either 0 or 1.
+     */
     public func write(bit: UInt8) {
         precondition(bit <= 1, "A bit must be either 0 or 1.")
 
@@ -41,13 +44,13 @@ public final class LsbBitWriter: BitWriter {
     }
 
     /**
-     Writes unsigned `number`, using and advancing by `bitsCount` BIT positions.
+     Writes an unsigned `number`, advancing by `bitsCount` bit positions.
 
-     - Note: If `bitsCount` is smaller than the actual amount of `number`'s bits then 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").
-     - Note: This method is especially useful when it is necessary to write an unsigned number which overflows and,
-     thus, crashes when converting to an `Int` if `write(number:bitsCount:)` method is used.
+     This method may be useful for writing numbers, that would cause an integer overflow crash if converted to `Int`.
+
+     - Note: The `number` will be truncated if the `bitsCount` is less than the amount of bits required to fully
+     represent the value of `number`.
+     - Note: Bits of the `number` are processed using the same bit-numbering scheme as of the writer (i.e. "LSB 0").
      */
     public func write(unsignedNumber: UInt, bitsCount: Int) {
         precondition(0...UInt.bitWidth ~= bitsCount)
@@ -59,20 +62,18 @@ public final class LsbBitWriter: BitWriter {
     }
 
     /**
-     Writes `byte`, advancing by one BYTE position.
+     Writes a `byte`, advancing by one byte position.
 
-     - Precondition: Writer MUST be aligned.
+     - Precondition: The 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.
+     Aligns a bit pointer to a byte boundary, i.e. moves the bit pointer to the first bit of the next byte, filling all
+     skipped bit positions with zeros. If the writer is already aligned, then does nothing.
      */
     public func align() {
         guard self.bitMask != 1

Sources/MsbBitWriter.swift

@@ -6,26 +6,29 @@
 import Foundation
 
 /**
- A type that contains functions for writing `Data` bit-by-bit (and byte-by-byte),
- assuming "MSB 0" bit numbering scheme.
+ A type that contains functions for writing `Data` bit-by-bit and byte-by-byte using "MSB 0" bit numbering scheme.
  */
 public final class MsbBitWriter: BitWriter {
 
-    /// Data which contains writer's output (the last byte in progress is not included).
+    /// Data which contains the writer's output (the last byte, that is currently being written, is not included).
     public private(set) var data: Data = Data()
 
     private var bitMask: UInt8 = 128
     private var currentByte: UInt8 = 0
 
-    /// True, if writer's BIT pointer is aligned with the BYTE border.
+    /// True, if a bit pointer is aligned to a byte boundary.
     public var isAligned: Bool {
         return self.bitMask == 128
     }
 
-    /// Creates an instance for writing bits (and bytes).
+    /// Creates an instance for writing bits and bytes.
     public init() { }
 
-    /// Writes `bit`, advancing by one BIT position.
+    /**
+     Writes a `bit`, advancing by one bit position.
+
+     - Precondition: The `bit` must be either 0 or 1.
+     */
     public func write(bit: UInt8) {
         precondition(bit <= 1, "A bit must be either 0 or 1.")
 
@@ -41,13 +44,13 @@ public final class MsbBitWriter: BitWriter {
     }
 
     /**
-     Writes unsigned `number`, using and advancing by `bitsCount` BIT positions.
+     Writes an unsigned `number`, advancing by `bitsCount` bit positions.
 
-     - Note: If `bitsCount` is smaller than the actual amount of `number`'s bits then 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. "MSB 0").
-     - Note: This method is especially useful when it is necessary to write an unsigned number which overflows and,
-     thus, crashes when converting to an `Int` if `write(number:bitsCount:)` method is used.
+     This method may be useful for writing numbers, that would cause an integer overflow crash if converted to `Int`.
+
+     - Note: The `number` will be truncated if the `bitsCount` is less than the amount of bits required to fully
+     represent the value of `number`.
+     - Note: Bits of the `number` are processed using the same bit-numbering scheme as of the writer (i.e. "MSB 0").
      */
     public func write(unsignedNumber: UInt, bitsCount: Int) {
         precondition(0...UInt.bitWidth ~= bitsCount)
@@ -59,20 +62,18 @@ public final class MsbBitWriter: BitWriter {
     }
 
     /**
-     Writes `byte`, advancing by one BYTE position.
+     Writes a `byte`, advancing by one byte position.
 
-     - Precondition: Writer MUST be aligned.
+     - Precondition: The 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.
+     Aligns a bit pointer to a byte boundary, i.e. moves the bit pointer to the first bit of the next byte, filling all
+     skipped bit positions with zeros. If the writer is already aligned, then does nothing.
      */
     public func align() {
         guard self.bitMask != 128