updated documentation

Author: odrobnik

Sources/SwiftMCP/Models/MCPTool.swift

@@ -67,14 +67,14 @@ extension MCPTool: Codable {
  */
 extension MCPTool {
 	/**
-	 Enriches the provided arguments dictionary with default values for missing parameters.
+	 Enriches a dictionary of arguments with default values for any missing parameters.
 
 	 - Parameters:
 	   - arguments: The original arguments dictionary
 	   - object: The object containing the function metadata
-	   - functionName: The name of the function to get default values for
 
 	 - Returns: A new dictionary with default values added for missing parameters
+	 - Throws: MCPToolError if required parameters are missing or if parameter conversion fails
 	 */
 	public func enrichArguments(_ arguments: [String: Any], forObject object: Any) throws -> [String: Any] {
 		// Use the provided function name or fall back to the tool's name
@@ -130,16 +130,26 @@ extension MCPTool {
  Extension to make JSONSchema conform to Codable
  */
 extension JSONSchema: Codable {
-	// MARK: - Codable Implementation
-	
+	/// Coding keys for JSONSchema encoding and decoding
 	private enum CodingKeys: String, CodingKey {
+		/// The type of the schema (string, number, boolean, array, or object)
 		case type
+		/// The properties of an object schema
 		case properties
+		/// The required properties of an object schema
 		case required
+		/// A description of the schema
 		case description
+		/// The schema for array items
 		case items
 	}
 
+	/**
+	 Creates a new JSONSchema instance by decoding from the given decoder.
+	 
+	 - Parameter decoder: The decoder to read data from
+	 - Throws: DecodingError if the data is corrupted or if an unsupported schema type is encountered
+	 */
 	public init(from decoder: Decoder) throws {
 		let container = try decoder.container(keyedBy: CodingKeys.self)
 		let type = try container.decode(String.self, forKey: .type)
@@ -173,6 +183,12 @@ extension JSONSchema: Codable {
 		}
 	}
 
+	/**
+	 Encodes this JSONSchema instance into the given encoder.
+	 
+	 - Parameter encoder: The encoder to write data to
+	 - Throws: EncodingError if the data cannot be encoded
+	 */
 	public func encode(to encoder: Encoder) throws {
 		var container = encoder.container(keyedBy: CodingKeys.self)
 
@@ -209,16 +225,31 @@ extension JSONSchema: Codable {
 
 /**
  A coding key that can be initialized with any string value.
+ Used for encoding and decoding dynamic property names in JSON schemas.
  */
 private struct AnyCodingKey: CodingKey {
+	/// The string value of the coding key
 	var stringValue: String
+	/// The integer value of the coding key, if any
 	var intValue: Int?
 
+	/**
+	 Creates a coding key from a string value.
+	 
+	 - Parameter stringValue: The string value for the key
+	 - Returns: A coding key, or nil if the string value is invalid
+	 */
 	init?(stringValue: String) {
 		self.stringValue = stringValue
 		self.intValue = nil
 	}
 
+	/**
+	 Creates a coding key from an integer value.
+	 
+	 - Parameter intValue: The integer value for the key
+	 - Returns: A coding key, or nil if the integer value is invalid
+	 */
 	init?(intValue: Int) {
 		self.stringValue = String(intValue)
 		self.intValue = intValue

Sources/SwiftMCP/Models/MCPToolMetadata.swift

@@ -17,27 +17,30 @@ public struct MCPToolMetadata: Sendable {
 
     /// The return type of the function, if any
     public let returnType: String?
-	
-	// an optional description of the returned value
-	public let returnTypeDescription: String?
-	
-	// If the tool is async
-	public let isAsync: Bool
-	
-	// If the tool throws
-	public let isThrowing: Bool
 
-    /// An optional description of the function
+    /// A description of what the function returns
+    public let returnTypeDescription: String?
+    
+    /// Whether the function is asynchronous
+    public let isAsync: Bool
+    
+    /// Whether the function can throw errors
+    public let isThrowing: Bool
+    
+    /// A description of the function's purpose
     public let description: String?
 
     /**
-     Creates a new tool metadata with the specified name, parameters, return type, and description.
+     Creates a new MCPToolMetadata instance.
 
      - Parameters:
        - name: The name of the function
+       - description: A description of the function's purpose
        - parameters: The parameters of the function
        - returnType: The return type of the function, if any
-       - description: An optional description of the function's purpose
+       - returnTypeDescription: A description of what the function returns
+       - isAsync: Whether the function is asynchronous
+       - isThrowing: Whether the function can throw errors
      */
     public init(name: String, description: String? = nil, parameters: [MCPToolParameterInfo], returnType: String? = nil, returnTypeDescription: String? = nil, isAsync: Bool = false, isThrowing: Bool = false) {
         self.name = name

Sources/SwiftMCP/OpenAPI/OpenAPISpec.swift

@@ -4,59 +4,82 @@ import Foundation
 public struct OpenAPISpec: Codable {
     /// Basic information about the API
     public struct Info: Codable {
+        /// The title of the API
         public let title: String
+        /// The version of the API
         public let version: String
+        /// A description of the API
         public let description: String
     }
 
     /// Server information
     public struct Server: Codable {
+        /// The server URL
         public let url: String
+        /// A description of the server
         public let description: String
     }
 
     /// Request or response content
     public struct Content: Codable {
+        /// The schema defining the content structure
         public let schema: JSONSchema
     }
 
     /// Request body specification
     public struct RequestBody: Codable {
+        /// Whether the request body is required
         public let required: Bool
+        /// The content types and their schemas
         public let content: [String: Content]
     }
 
     /// Response specification
     public struct Response: Codable {
+        /// A description of the response
         public let description: String
+        /// The content types and their schemas, if any
         public let content: [String: Content]?
     }
 
     /// Operation (e.g., POST) specification
     public struct Operation: Codable {
+        /// A brief summary of what the operation does
         public let summary: String
+        /// Unique identifier for the operation
         public let operationId: String
+        /// A detailed description of the operation
         public let description: String
+        /// The request body specification, if any
         public let requestBody: RequestBody?
+        /// The possible responses keyed by status code
         public let responses: [String: Response]
     }
 
     /// Path item specification
     public struct PathItem: Codable {
+        /// The POST operation specification, if any
         public let post: Operation?
     }
 
+    /// The OpenAPI specification version
     public let openapi: String
+    /// Basic information about the API
     public let info: Info
+    /// The servers where the API is available
     public let servers: [Server]
+    /// The available paths and their operations
     public let paths: [String: PathItem]
 
-    /// Creates an OpenAPI specification for an MCP server
-    /// - Parameters:
-    ///   - server: The MCP server to create the spec for
-    ///   - host: The host where the server is running
-    ///   - port: The port where the server is running
-	public init(server: MCPServer, scheme: String, host: String) {
+    /**
+     Creates an OpenAPI specification for an MCP server
+     
+     - Parameters:
+       - server: The MCP server to create the spec for
+       - scheme: The URL scheme to use (e.g., "http" or "https")
+       - host: The host where the server is running
+     */
+    public init(server: MCPServer, scheme: String, host: String) {
         self.openapi = "3.1.0"
         self.info = Info(
             title: "\(server.name) API",

Sources/SwiftMCP/Transport/HTTPLogger.swift

@@ -5,11 +5,11 @@ import NIOHTTP1
 import NIOConcurrencyHelpers
 
 /// A channel handler that logs both incoming and outgoing HTTP messages
-public final class HTTPLogger: ChannelDuplexHandler {
-	public typealias InboundIn = HTTPServerRequestPart
-	public typealias InboundOut = HTTPServerRequestPart
-	public typealias OutboundIn = HTTPServerResponsePart
-	public typealias OutboundOut = HTTPServerResponsePart
+final class HTTPLogger: ChannelDuplexHandler {
+	typealias InboundIn = HTTPServerRequestPart
+	typealias InboundOut = HTTPServerRequestPart
+	typealias OutboundIn = HTTPServerResponsePart
+	typealias OutboundOut = HTTPServerResponsePart
 
 	private let httpLogger = Logger(label: "com.cocoanetics.SwiftMCP.HTTP")
 	private let lock = NIOLock()
@@ -21,7 +21,7 @@ public final class HTTPLogger: ChannelDuplexHandler {
 	private var currentResponseBody = ""
 
 	/// Log incoming requests and forward them to the next handler
-	public func channelRead(context: ChannelHandlerContext, data: NIOAny) {
+	func channelRead(context: ChannelHandlerContext, data: NIOAny) {
 		let reqPart = unwrapInboundIn(data)
 
 		lock.withLock {
@@ -49,7 +49,7 @@ public final class HTTPLogger: ChannelDuplexHandler {
 	}
 
 	/// Log outgoing responses and forward them to the next handler
-	public func write(context: ChannelHandlerContext, data: NIOAny, promise: EventLoopPromise<Void>?) {
+	func write(context: ChannelHandlerContext, data: NIOAny, promise: EventLoopPromise<Void>?) {
 		let resPart = unwrapOutboundIn(data)
 
 		lock.withLock {
@@ -78,7 +78,7 @@ public final class HTTPLogger: ChannelDuplexHandler {
 		context.write(data, promise: promise)
 	}
 
-	public func flush(context: ChannelHandlerContext) {
+	func flush(context: ChannelHandlerContext) {
 		context.flush()
 	}
 
@@ -110,7 +110,7 @@ public final class HTTPLogger: ChannelDuplexHandler {
 		httpLogger.trace("\(log)")
 	}
 
-	public func handlerAdded(context: ChannelHandlerContext) {
+	func handlerAdded(context: ChannelHandlerContext) {
 		lock.withLock {
 			currentRequestHead = nil
 			currentRequestBody = ""
@@ -119,7 +119,7 @@ public final class HTTPLogger: ChannelDuplexHandler {
 		}
 	}
 
-	public func handlerRemoved(context: ChannelHandlerContext) {
+	func handlerRemoved(context: ChannelHandlerContext) {
 		lock.withLock {
 			// Log any pending messages
 			logCurrentRequest()