Add doc comments for GDBHostCommandDecoder

Author: MaxDesiatov

Sources/GDBRemoteProtocol/GDBHostCommand.swift

@@ -16,11 +16,6 @@
 /// * https://sourceware.org/gdb/current/onlinedocs/gdb.html/General-Query-Packets.html
 /// * https://lldb.llvm.org/resources/lldbgdbremote.html
 package struct GDBHostCommand: Equatable {
-    enum Error: Swift.Error {
-        case unexpectedArgumentsValue
-        case unknownCommand(kind: String, arguments: String)
-    }
-
     package enum Kind: String, Equatable {
         // Currently listed in the order that LLDB sends them in.
         case startNoAckMode
@@ -94,8 +89,12 @@ package struct GDBHostCommand: Equatable {
 
     /// Arguments supplied with a host command.
     package let arguments: String
-
-    package init(kindString: String, arguments: String) throws {
+    
+    /// Initialize a host command from raw strings sent from a host.
+    /// - Parameters:
+    ///   - kindString: raw ``String`` that denotes kind of the command.
+    ///   - arguments: raw arguments that immediately follow kind of the command.
+    package init(kindString: String, arguments: String) throws(GDBHostCommandDecoder.Error) {
         let registerInfoPrefix = "qRegisterInfo"
 
         if kindString.starts(with: "x") {
@@ -110,20 +109,20 @@ package struct GDBHostCommand: Equatable {
             self.kind = .registerInfo
 
             guard arguments.isEmpty else {
-                throw Error.unexpectedArgumentsValue
+                throw GDBHostCommandDecoder.Error.unexpectedArgumentsValue
             }
             self.arguments = String(kindString.dropFirst(registerInfoPrefix.count))
             return
         } else if let kind = Kind(rawValue: kindString) {
             self.kind = kind
         } else {
-            throw Error.unknownCommand(kind: kindString, arguments: arguments)
+            throw GDBHostCommandDecoder.Error.unknownCommand(kind: kindString, arguments: arguments)
         }
 
         self.arguments = arguments
     }
 
-    /// Memberwise initializer of `GDBHostCommand` type.
+    /// Member-wise initializer of `GDBHostCommand` type.
     package init(kind: Kind, arguments: String) {
         self.kind = kind
         self.arguments = arguments

Sources/GDBRemoteProtocol/GDBHostCommandDecoder.swift

@@ -14,58 +14,93 @@ import Logging
 import NIOCore
 
 extension ByteBuffer {
+    /// Returns `true` if byte to be read immediately is a GDB RP checksum
+    /// delimiter. Returns `false` otherwise.
     var isChecksumDelimiterAtReader: Bool {
         self.peekInteger(as: UInt8.self) == UInt8(ascii: "#")
     }
 
+    /// Returns `true` if byte to be read immediately is a GDB RP command arguments
+    /// delimiter. Returns `false` otherwise.
     var isArgumentsDelimiterAtReader: Bool {
         self.peekInteger(as: UInt8.self) == UInt8(ascii: ":")
     }
 }
 
+/// Decoder of GDB RP host commands, that takes raw `ByteBuffer` as an input encoded
+/// per https://sourceware.org/gdb/current/onlinedocs/gdb.html/Overview.html#Overview
+/// and produces a `GDBPacket<GDBHostCommand>` value as output. This decoder is
+/// compatible with NIO channel pipelines, making it easy to integrate with different
+/// I/O configurations.
 package struct GDBHostCommandDecoder: ByteToMessageDecoder {
-    enum Error: Swift.Error {
+    /// Errors that can be thrown during host command decoding.
+    package enum Error: Swift.Error {
+        /// Expected `+` acknowledgement character to be included in the packet, when
+        /// ``GDBHostCommandDecoder/isNoAckModeActive`` is set to `false`.
         case expectedAck
+
+        /// Expected command to start with `$` character`.
         case expectedCommandStart
-        case unknownCommandKind(String)
+
+        /// Expected checksum to be included with the packet was not found.
         case expectedChecksum
+
+        /// Expected checksum included with the packet did not match the expected value.
         case checksumIncorrect(expectedChecksum: Int, receivedChecksum: UInt8)
+
+        /// Unexpected arguments value supplied for a given command.
+        case unexpectedArgumentsValue
+
+        /// Host command kind could not be parsed. See `GDBHostCommand.Kind` for the
+        /// list of supported commands.
+        case unknownCommand(kind: String, arguments: String)
     }
 
+    /// Type of the output value produced by this decoder.
     package typealias InboundOut = GDBPacket<GDBHostCommand>
 
     private var accumulatedDelimiter: UInt8?
 
     private var accummulatedKind = [UInt8]()
     private var accummulatedArguments = [UInt8]()
-
+    
+    /// Logger instance used by this decoder.
     private let logger: Logger
-
+    
+    /// Initializes a new decoder.
+    /// - Parameter logger: logger instance that consumes messages from the newly
+    /// initialized decoder.
     package init(logger: Logger) { self.logger = logger }
-
+    
+    /// Sum of the raw character values consumed in the current command so far,
+    /// used in checksum computation.
     private var accummulatedSum = 0
+
+    /// Computed checksum for the values consumed in the current command so far.
     package var accummulatedChecksum: UInt8 {
         UInt8(self.accummulatedSum % 256)
     }
 
     private var isNoAckModeRequested = false
     private var isNoAckModeActive = false
 
-    mutating package func decode(buffer: inout ByteBuffer) throws -> GDBPacket<GDBHostCommand>? {
+    package mutating func decode(
+        buffer: inout ByteBuffer
+    ) throws(Error) -> GDBPacket<GDBHostCommand>? {
         guard var startDelimiter = self.accumulatedDelimiter ?? buffer.readInteger(as: UInt8.self) else {
             // Not enough data to parse.
             return nil
         }
 
-        if !isNoAckModeActive {
+        if !self.isNoAckModeActive {
             let firstStartDelimiter = startDelimiter
 
             guard firstStartDelimiter == UInt8(ascii: "+") else {
                 logger.error("unexpected ack character: \(Character(UnicodeScalar(startDelimiter)))")
                 throw Error.expectedAck
             }
 
-            if isNoAckModeRequested {
+            if self.isNoAckModeRequested {
                 self.isNoAckModeActive = true
             }
 
@@ -82,7 +117,7 @@ package struct GDBHostCommandDecoder: ByteToMessageDecoder {
 
         // Command start delimiters.
         guard startDelimiter == UInt8(ascii: "$") else {
-            logger.error("unexpected delimiter: \(Character(UnicodeScalar(startDelimiter)))")
+            self.logger.error("unexpected delimiter: \(Character(UnicodeScalar(startDelimiter)))")
             throw Error.expectedCommandStart
         }
 
@@ -151,7 +186,7 @@ package struct GDBHostCommandDecoder: ByteToMessageDecoder {
     mutating package func decode(
         context: ChannelHandlerContext,
         buffer: inout ByteBuffer
-    ) throws -> DecodingState {
+    ) throws(Error) -> DecodingState {
         logger.trace(.init(stringLiteral: buffer.peekString(length: buffer.readableBytes)!))
 
         guard let command = try self.decode(buffer: &buffer) else {

Sources/GDBRemoteProtocol/GDBPacket.swift

@@ -10,6 +10,11 @@
 //
 //===----------------------------------------------------------------------===//
 
+/// GDB host commands and target responses are wrapped with delimiters followed
+/// by a single byte checksum value. This type denotes such a packet by attaching
+/// a checksum value to the contained payload.
+/// See GDB remote protocol overview for more details:
+/// https://sourceware.org/gdb/current/onlinedocs/gdb.html/Overview.html#Overview
 package struct GDBPacket<Payload: Sendable>: Sendable {
     package let payload: Payload
     package let checksum: UInt8