Sources/DiscogsService/Catalogs/DiscogsService.docc/Library.md

@@ -1,10 +1,10 @@
 # ``DiscogsService``
 
-<!--@START_MENU_TOKEN@-->Summary<!--@END_MENU_TOKEN@-->
+A Swift client library for the Discogs API, built on top of Swift OpenAPI.
 
 ## Overview
 
-<!--@START_MENU_TOKEN@-->Text<!--@END_MENU_TOKEN@-->
+This library provides a type-safe client for interacting with the [Discogs API](https://www.discogs.com/developers), including endpoints for the database, user identity, user collections, wantlists, lists, and the marketplace. It supports multiple authentication methods and transports credentials via headers or query parameters.
 
 ## Topics
 

Sources/DiscogsService/Internal/Extensions/String+Constants.swift

@@ -16,7 +16,7 @@ extension String {
     /// An empty string.
     static let empty = ""
     
-    /// A namespaces assigned for the names of parameters.
+    /// A namespace for the names of parameters.
     enum Parameter {
         /// A name for the consumer key.
         static let key = "key"
@@ -25,9 +25,9 @@ extension String {
         /// A name for the user token.
         static let token = "token"
     }
-    /// A namespaces assigned for the formats of string values.
+    /// A namespace for the formats of string values.
     enum Format {}
     
-    /// A namespaces assigned for the formats of regular expression patterns.
+    /// A namespace for the formats of regular expression patterns.
     enum Pattern {}
 }

Sources/DiscogsService/Internal/Validation Rules/CamelCaseValidationRule.swift

@@ -52,7 +52,7 @@ private extension CamelCaseValidationRule {
     ///
     /// - Parameter input: An input to be validated.
     /// - Returns: A flag that indicates whether a given input has been validated or not.
-    /// - Throws: An error of type ``InputValidatorError`` in case the validation failed.
+    /// - Throws: An error of type ``InputValidationError`` in case the validation failed.
     func validate(input: String?) throws -> Bool {
         guard let input else {
             return false

Sources/DiscogsService/Internal/Validation Rules/NotEmptyValidationRule.swift

@@ -52,7 +52,7 @@ private extension NotEmptyValidationRule {
     ///
     /// - Parameter input: An input to be validated.
     /// - Returns: A flag that indicates whether a given input has been validated or not.
-    /// - Throws: An error of type ``InputValidatorError`` in case the validation failed.
+    /// - Throws: An error of type ``InputValidationError`` in case the validation failed.
     func validate(input: String?) throws -> Bool {
         guard let input else {
             return false

Sources/DiscogsService/Internal/Validation Rules/NotNilValidationRule.swift

@@ -52,7 +52,7 @@ private extension NotNilValidationRule {
     /// 
     /// - Parameter input: An input to be validated.
     /// - Returns: A flag that indicates whether a given input has been validated or not.
-    /// - Throws: An error of type ``InputValidatorError`` in case the validation failed.
+    /// - Throws: An error of type ``InputValidationError`` in case the validation failed.
     func validate(input: String?) throws -> Bool {
         guard input != nil else {
             throw InputValidationError.inputIsNil

Sources/DiscogsService/Internal/Validation Rules/SecureValidationRule.swift

@@ -65,9 +65,9 @@ extension InputValidationRule where Self == SecureValidationRule {
 enum SecurityInput: Int {
     /// A consumer key is 20 characters long.
     case consumerKey = 20
-    /// A consumer key is 32 characters long.
+    /// A consumer secret is 32 characters long.
     case consumerSecret = 32
-    /// A consumer key is 40 characters long.
+    /// A user token is 40 characters long.
     case userToken = 40
 }
 
@@ -83,7 +83,7 @@ private extension SecureValidationRule {
     ///
     /// - Parameter input: An input to be validated.
     /// - Returns: A flag that indicates whether a given input has been validated or not.
-    /// - Throws: An error of type ``InputValidatorError`` in case the validation failed.
+    /// - Throws: An error of type ``InputValidationError`` in case the validation failed.
     func validate(input: String?) throws -> Bool {
         guard let input else {
             return false

Sources/DiscogsService/Internal/Validation Rules/SemanticVersionValidationRule.swift

@@ -54,7 +54,7 @@ private extension SemanticVersionValidationRule {
     ///
     /// - Parameter input: An input to be validated.
     /// - Returns: A flag that indicates whether a given input has been validated or not.
-    /// - Throws: An error of type ``InputValidatorError`` in case the validation failed.
+    /// - Throws: An error of type ``InputValidationError`` in case the validation failed.
     func validate(input: String?) throws -> Bool {
         guard let input else {
             return false

Sources/DiscogsService/Internal/Validation Rules/URLValidationRule.swift

@@ -56,7 +56,7 @@ private extension URLValidationRule {
     ///
     /// - Parameter input: An input to be validated.
     /// - Returns: A flag that indicates whether a given input has been validated or not.
-    /// - Throws: An error of type ``InputValidatorError`` in case the validation failed.
+    /// - Throws: An error of type ``InputValidationError`` in case the validation failed.
     func validate(input: String?) throws -> Bool {
         guard let input else {
             return false

Sources/DiscogsService/Public/Definitions/References.swift

@@ -12,5 +12,7 @@
 //
 // ===----------------------------------------------------------------------===
 
-/// A reference to a live (or production) service defined in the OpenAPI document.
+/// A type alias for the live (production) Discogs API server defined in the OpenAPI document.
+///
+/// Use this as the `serverURL` when initializing a ``Client`` to connect to the production Discogs API.
 public typealias LiveService = Servers.Server1

Sources/DiscogsService/Public/Enumerations/AuthTransport.swift

@@ -13,8 +13,11 @@
 // ===----------------------------------------------------------------------===
 
 /// A representation of the available transport options to send credentials in authenticated requests.
+///
+/// This enumeration is used in conjunction with ``AuthMiddleware`` to determine how authentication credentials
+/// are attached to outgoing requests.
 public enum AuthTransport: CaseIterable, Sendable {
-    /// Authentication credential are sent in a request as an `Authentication` header.
+    /// Authentication credentials are sent in a request as an `Authorization` header.
     ///
     /// This means that the header will be added to any existing header in a request, like this:
     /// ```bash
@@ -22,7 +25,7 @@ public enum AuthTransport: CaseIterable, Sendable {
     /// curl "https://api.discogs.com/database/search?q=Slayer" -H "Authorization: Discogs token=abcxyz123456"
     /// ```
     case onHeader
-    /// Authentication credential are sent in a request as parameters in the query string.
+    /// Authentication credentials are sent in a request as parameters in the query string.
     ///
     /// This means that the parameters will be injected into the query in a request, like this:
     /// ```bash

Sources/DiscogsService/Public/Errors/InputValidationError.swift

@@ -12,7 +12,7 @@
 //
 // ===----------------------------------------------------------------------===
 
-/// A representation of all the possible validation error that could be thrown while validating an input.
+/// A representation of all the possible validation errors that could be thrown while validating an input.
 public enum InputValidationError: Error {
     /// An input is empty.
     case inputIsEmpty

Sources/DiscogsService/Public/Middlewares/AuthMiddleware.swift

@@ -110,6 +110,14 @@ extension AuthMiddleware: ClientMiddleware {
     
     // MARK: Functions
     
+    /// Intercepts an outgoing HTTP request and injects authentication credentials if configured.
+    /// - Parameters:
+    ///   - request: The outgoing HTTP request to potentially authenticate.
+    ///   - body: The optional body of the HTTP request.
+    ///   - baseURL: The base URL of the service.
+    ///   - operationID: The identifier of the API operation being called.
+    ///   - next: The next middleware or transport to call in the chain.
+    /// - Returns: The HTTP response and optional response body from the service.
     public func intercept(
         _ request: HTTPRequest,
         body: HTTPBody?,

Sources/DiscogsService/Public/Middlewares/UserAgentMiddleware.swift

@@ -60,6 +60,14 @@ extension UserAgentMiddleware: ClientMiddleware {
     
     // MARK: Functions
     
+    /// Intercepts an outgoing HTTP request and attaches the `User-Agent` header.
+    /// - Parameters:
+    ///   - request: The outgoing HTTP request to modify.
+    ///   - body: The optional body of the HTTP request.
+    ///   - baseURL: The base URL of the service.
+    ///   - operationID: The identifier of the API operation being called.
+    ///   - next: The next middleware or transport to call in the chain.
+    /// - Returns: The HTTP response and optional response body from the service.
     public func intercept(
         _ request: HTTPRequest,
         body: HTTPBody?,

Sources/DiscogsService/Public/Models/Product.swift

@@ -14,27 +14,32 @@
 
 import Foundation
 
-/// A type that represents a product that uses the ``Client`` client.
+/// A representation of the product information used to generate the `User-Agent` header for requests to the Discogs API.
+///
+/// The Discogs API requires a `User-Agent` header that identifies the application making the request. This model captures
+/// the product name, version, and URL needed to build that header via the ``UserAgentMiddleware``.
+///
+/// The generated `User-Agent` header follows the format: `ProductName/1.0.0 +https://example.com`
 public struct Product: Sendable {
     
     // MARK: Properties
     
-    /// A camel-cased name of a product.
+    /// The camel-cased name of the product (e.g., `MyDiscogsApp`).
     let name: String
     
-    /// A URI link related to a product.
+    /// A URI link related to the product (e.g., `https://example.com`).
     let url: String
     
-    /// A semantic version of a product.
+    /// The semantic version of the product (e.g., `1.0.0`).
     let version: String
     
     // MARK: Initializers
     
     /// Initializes this model.
     /// - Parameters:
-    ///   - name: A camel-cased name of a product.
-    ///   - version: A semantic version of a product.
-    ///   - url: A URI link related to a product.
+    ///   - name: The camel-cased name of the product.
+    ///   - version: The semantic version of the product, following [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).
+    ///   - url: A URI link related to the product.
     public init(
         name: String,
         version: String,