diff --git a/Sources/MQ/Errors/Cancelled.swift b/Sources/MQ/Errors/Cancelled.swift index b15b9b6..508b1d3 100644 --- a/Sources/MQ/Errors/Cancelled.swift +++ b/Sources/MQ/Errors/Cancelled.swift @@ -10,7 +10,7 @@ public struct Cancelled: TheError { /// - message: Message associated with this error. /// Default value is "Cancelled". /// - displayableMessage: Message which can be displayed - /// to the end user. Default is "Cancelled". + /// to the end user. Default value is based on ``TheErrorDisplayableMessages``. /// - file: Source code file identifier. /// Filled automatically based on compile time constants. /// - line: Line in given source code file. diff --git a/Sources/MQ/Errors/InternalInconsistency.swift b/Sources/MQ/Errors/InternalInconsistency.swift index a9d93f4..e2ff6e1 100644 --- a/Sources/MQ/Errors/InternalInconsistency.swift +++ b/Sources/MQ/Errors/InternalInconsistency.swift @@ -8,7 +8,7 @@ public struct InternalInconsistency: TheError { /// - Parameters: /// - message: Message associated with this error. /// - displayableMessage: Message which can be displayed - /// to the end user. Default is "Internal inconsistency error". + /// to the end user. Default value is based on ``TheErrorDisplayableMessages``. /// - file: Source code file identifier. /// Filled automatically based on compile time constants. /// - line: Line in given source code file. diff --git a/Sources/MQ/Errors/StringEncodingFailure.swift b/Sources/MQ/Errors/StringEncodingFailure.swift index 7b7b929..2702403 100644 --- a/Sources/MQ/Errors/StringEncodingFailure.swift +++ b/Sources/MQ/Errors/StringEncodingFailure.swift @@ -13,6 +13,8 @@ public struct StringEncodingFailure: TheError { /// This value will not be collected in release builds. /// - message: Message associated with this error. /// Default value is "StringEncodingFailure". + /// - displayableMessage: Custom message that could be + /// displayed to the end user. Default value is based on ``TheErrorDisplayableMessages``. /// - file: Source code file identifier. /// Filled automatically based on compile time constants. /// - line: Line in given source code file. diff --git a/Sources/MQ/Errors/TheErrorDisplayableMessages.swift b/Sources/MQ/Errors/TheErrorDisplayableMessages.swift index 4fe0c10..dd3625d 100644 --- a/Sources/MQ/Errors/TheErrorDisplayableMessages.swift +++ b/Sources/MQ/Errors/TheErrorDisplayableMessages.swift @@ -1,3 +1,5 @@ +/// Container for displayable error messages. +/// /// ``TheErrorDisplayableMessages`` is a container /// holding default ``DisplayableMessage`` for errors /// based on the error type. @@ -29,8 +31,11 @@ public enum TheErrorDisplayableMessages { /// In orded to customize messages use /// ``TheErrorDisplayableMessages.setMessage(_:for:)`` or /// ``TheErrorDisplayableMessages.setMessage(_:forGroup:)``. + /// + /// - Parameter errorType: Type of the error used to request + /// displayable message. @inlinable @Sendable public static func message( - for _: ErrorType.Type + for errorType: ErrorType.Type ) -> DisplayableString where ErrorType: TheError { self.storage.access { (messages: inout Dictionary) -> DisplayableString in @@ -63,13 +68,18 @@ public enum TheErrorDisplayableMessages { /// Message can be set only once and only /// if it was not requested before. /// + /// - Parameters: + /// - message: Message to be assigned to the error type. + /// - errorType: Type of the error which will + /// be associated with the message. + /// /// - Note: Assigned message will be cached /// and reused. Make sure that it does not /// provide dynamic value that is expected /// to be changing over time. @inlinable @Sendable public static func setMessage( _ message: DisplayableString, - for _: ErrorType.Type + for errorType: ErrorType.Type ) where ErrorType: TheError { self.storage.access { (messages: inout Dictionary) -> Void in runtimeAssert( @@ -88,6 +98,11 @@ public enum TheErrorDisplayableMessages { /// to use customized message. /// Message can be set only once. /// + /// - Parameters: + /// - message: Message to be assigned to the error group identifier. + /// - groupIdentifier: Group identifier which will be + /// associated with the message. + /// /// - Note: Assigned message will be cached /// and reused. Make sure that it does not /// provide dynamic value that is expected @@ -105,13 +120,15 @@ public enum TheErrorDisplayableMessages { } } - /// Set the default message for errors. + /// Set the default message for all errors. /// /// Associate message with the default error group. /// If default message is not set error type will be /// used as the message. /// Message can be set only once. /// + /// - Parameter message: Message to be assigned as default message for all errors. + /// /// - Note: Assigned message will be cached /// and reused. Make sure that it does not /// provide dynamic value that is expected diff --git a/Sources/MQ/Errors/TheErrorGroup.swift b/Sources/MQ/Errors/TheErrorGroup.swift index 1c03536..4ec6c58 100644 --- a/Sources/MQ/Errors/TheErrorGroup.swift +++ b/Sources/MQ/Errors/TheErrorGroup.swift @@ -1,3 +1,13 @@ +/// Group of errors. +/// +/// ``TheErrorGroup`` is a structure used to tag +/// errors to allow easier grouping and hadling +/// of similar or related errors. +/// +/// - Note: ``TheErrorGroup`` can be defined using +/// more than one identifier. Order of identifiers +/// mattrers. It is used i.e. to find matching +/// messages from ``TheErrorDisplayableMessages``. public struct TheErrorGroup { private var identifiers: Array @@ -5,6 +15,7 @@ public struct TheErrorGroup { extension TheErrorGroup { + /// Identifier of error group. public struct Identifier { private let identifier: StaticString @@ -13,6 +24,7 @@ extension TheErrorGroup { extension TheErrorGroup.Identifier: Hashable {} +// swift-format-ignore: AllPublicDeclarationsHaveDocumentation extension TheErrorGroup.Identifier: ExpressibleByStringLiteral { public init( @@ -24,6 +36,7 @@ extension TheErrorGroup.Identifier: ExpressibleByStringLiteral { extension TheErrorGroup: Hashable {} +// swift-format-ignore: AllPublicDeclarationsHaveDocumentation extension TheErrorGroup: ExpressibleByStringLiteral { public init( @@ -33,6 +46,7 @@ extension TheErrorGroup: ExpressibleByStringLiteral { } } +// swift-format-ignore: AllPublicDeclarationsHaveDocumentation extension TheErrorGroup: ExpressibleByArrayLiteral { public init( @@ -44,7 +58,13 @@ extension TheErrorGroup: ExpressibleByArrayLiteral { extension TheErrorGroup { + /// Default error group. + /// + /// All errors are implicitly matching this group. public static let `default`: Self = .init() +} + +extension TheErrorGroup { @usableFromInline internal func firstMatchingIdentifier( _ matches: (Identifier) -> Bool diff --git a/Sources/MQ/Synchronization/CriticalSection.swift b/Sources/MQ/Synchronization/CriticalSection.swift index d560ccb..01f8926 100644 --- a/Sources/MQ/Synchronization/CriticalSection.swift +++ b/Sources/MQ/Synchronization/CriticalSection.swift @@ -22,7 +22,7 @@ where State: Sendable { /// Initialize ``CriticalSection`` with given initial state. /// - /// - Properties: + /// - Parameters: /// - state: Initial state. /// - cleanup: Code executed on deallocation. public init( diff --git a/Sources/MQ/Utilities/IID.swift b/Sources/MQ/Utilities/IID.swift index ad2ad6c..4791052 100644 --- a/Sources/MQ/Utilities/IID.swift +++ b/Sources/MQ/Utilities/IID.swift @@ -22,7 +22,7 @@ // swift-format-ignore: AllPublicDeclarationsHaveDocumentation public var wrappedValue: IID { self } - /// Create new instance of IID + /// Create new instance of IID. public init() {} }