From 64b3fa47af82f40a61cf4648e1a6ba62d05c43ac Mon Sep 17 00:00:00 2001 From: Davide De Rosa Date: Fri, 23 Sep 2022 21:45:04 +0200 Subject: [PATCH] Add some missing documentation --- Sources/TunnelKitCore/CoreConfiguration.swift | 10 +++++++++- Sources/TunnelKitCore/DataCount.swift | 5 ++++- Sources/TunnelKitCore/DataUnit.swift | 15 ++++++++++----- Sources/TunnelKitCore/Endpoint.swift | 6 ++---- Sources/TunnelKitCore/SecureRandom.swift | 5 +++++ Sources/TunnelKitManager/Keychain.swift | 3 +-- .../NetworkExtensionConfiguration.swift | 6 +++++- Sources/TunnelKitManager/VPN.swift | 2 ++ Sources/TunnelKitOpenVPNCore/Configuration.swift | 13 +++++-------- .../ConfigurationParser.swift | 1 + .../OpenVPN+ProviderConfiguration.swift | 11 +++-------- .../WireGuard+ProviderConfiguration.swift | 5 +---- 12 files changed, 48 insertions(+), 34 deletions(-) diff --git a/Sources/TunnelKitCore/CoreConfiguration.swift b/Sources/TunnelKitCore/CoreConfiguration.swift index a338071..dd1f9a7 100644 --- a/Sources/TunnelKitCore/CoreConfiguration.swift +++ b/Sources/TunnelKitCore/CoreConfiguration.swift @@ -36,9 +36,13 @@ import Foundation +/// Global library settings. public class CoreConfiguration { + + /// Unique identifier of the library. public static let identifier = "com.algoritmico.TunnelKit" + /// Library version as seen in `Info.plist`. public static let version: String = { let bundle = Bundle(for: CoreConfiguration.self) guard let info = bundle.infoDictionary else { @@ -54,15 +58,19 @@ public class CoreConfiguration { return info["CFBundleShortVersionString"] as? String ?? "" }() - // configurable + /// Masks private data in logs. public static var masksPrivateData = true + /// String representing library version. public static var versionIdentifier: String? + /// Enables logging of sensitive data (hardcoded to false). public static let logsSensitiveData = false } extension CustomStringConvertible { + + /// Returns a masked version of `description` in case `CoreConfiguration.masksPrivateData` is `true`. public var maskedDescription: String { guard CoreConfiguration.masksPrivateData else { return description diff --git a/Sources/TunnelKitCore/DataCount.swift b/Sources/TunnelKitCore/DataCount.swift index c98824b..45d2db1 100644 --- a/Sources/TunnelKitCore/DataCount.swift +++ b/Sources/TunnelKitCore/DataCount.swift @@ -25,10 +25,13 @@ import Foundation -/// :nodoc: +/// A pair of received/sent bytes count. public struct DataCount: Equatable { + + /// Received bytes count. public let received: UInt + /// Sent bytes count. public let sent: UInt public init(_ received: UInt, _ sent: UInt) { diff --git a/Sources/TunnelKitCore/DataUnit.swift b/Sources/TunnelKitCore/DataUnit.swift index e09ca41..8e45ba6 100644 --- a/Sources/TunnelKitCore/DataUnit.swift +++ b/Sources/TunnelKitCore/DataUnit.swift @@ -25,7 +25,7 @@ import Foundation -/// :nodoc: +/// Helps expressing integers in bytes, kB, MB, GB. public enum DataUnit: UInt, CustomStringConvertible { case byte = 1 @@ -68,8 +68,14 @@ public enum DataUnit: UInt, CustomStringConvertible { } } -/// :nodoc: -extension UInt { +/// Supports being represented in data unit. +public protocol DataUnitRepresentable { + + /// Returns self expressed in bytes, kB, MB, GB. + var descriptionAsDataUnit: String { get } +} + +extension UInt: DataUnitRepresentable { private static let allUnits: [DataUnit] = [ .gigabyte, .megabyte, @@ -94,8 +100,7 @@ extension UInt { } } -/// :nodoc: -extension Int { +extension Int: DataUnitRepresentable { public var descriptionAsDataUnit: String { return UInt(self).descriptionAsDataUnit } diff --git a/Sources/TunnelKitCore/Endpoint.swift b/Sources/TunnelKitCore/Endpoint.swift index 5d2ffe9..5f2b11b 100644 --- a/Sources/TunnelKitCore/Endpoint.swift +++ b/Sources/TunnelKitCore/Endpoint.swift @@ -31,8 +31,7 @@ public struct Endpoint: RawRepresentable, Codable, Equatable, CustomStringConver public let proto: EndpointProtocol - /// :nodoc: - public init(_ address: String, _ proto: EndpointProtocol) { + public init(_ address: String, _ proto: EndpointProtocol) { self.address = address self.proto = proto } @@ -74,8 +73,7 @@ public struct EndpointProtocol: RawRepresentable, Equatable, CustomStringConvert /// The remote port. public let port: UInt16 - /// :nodoc: - public init(_ socketType: SocketType, _ port: UInt16) { + public init(_ socketType: SocketType, _ port: UInt16) { self.socketType = socketType self.port = port } diff --git a/Sources/TunnelKitCore/SecureRandom.swift b/Sources/TunnelKitCore/SecureRandom.swift index aaf6e57..e1b97d6 100644 --- a/Sources/TunnelKitCore/SecureRandom.swift +++ b/Sources/TunnelKitCore/SecureRandom.swift @@ -39,11 +39,16 @@ import Security.SecRandom import CTunnelKitCore import __TunnelKitUtils +/// Errors returned by `SecureRandom`. public enum SecureRandomError: Error { + + /// RNG could not be initialized. case randomGenerator } +/// Generates random data in a secure fashion. public class SecureRandom { + @available(*, deprecated) static func uint32FromBuffer() throws -> UInt32 { var randomBuffer = [UInt8](repeating: 0, count: 4) diff --git a/Sources/TunnelKitManager/Keychain.swift b/Sources/TunnelKitManager/Keychain.swift index 9928b50..564df45 100644 --- a/Sources/TunnelKitManager/Keychain.swift +++ b/Sources/TunnelKitManager/Keychain.swift @@ -328,8 +328,7 @@ public class Keychain { // MARK: Helpers - /// :nodoc: - public func setScope(query: inout [String: Any], context: String, userDefined: String?) { + public func setScope(query: inout [String: Any], context: String, userDefined: String?) { if let accessGroup = accessGroup { query[kSecAttrAccessGroup as String] = accessGroup #if os(macOS) diff --git a/Sources/TunnelKitManager/NetworkExtensionConfiguration.swift b/Sources/TunnelKitManager/NetworkExtensionConfiguration.swift index 49022ad..bfd1f1b 100644 --- a/Sources/TunnelKitManager/NetworkExtensionConfiguration.swift +++ b/Sources/TunnelKitManager/NetworkExtensionConfiguration.swift @@ -26,12 +26,16 @@ import Foundation import NetworkExtension -/// :nodoc: +/// Extra configuration parameters to attach optionally to a `NetworkExtensionConfiguration`. public struct NetworkExtensionExtra { + + /// A password reference to the keychain. public var passwordReference: Data? + /// A set of on-demand rules. public var onDemandRules: [NEOnDemandRule] = [] + /// Disconnects on sleep if `true`. public var disconnectsOnSleep = false public init() { diff --git a/Sources/TunnelKitManager/VPN.swift b/Sources/TunnelKitManager/VPN.swift index 3991718..3c5e764 100644 --- a/Sources/TunnelKitManager/VPN.swift +++ b/Sources/TunnelKitManager/VPN.swift @@ -85,6 +85,8 @@ public protocol VPN { } extension DispatchTimeInterval { + + /// Returns self in nanoseconds. public var nanoseconds: UInt64 { switch self { case .seconds(let sec): diff --git a/Sources/TunnelKitOpenVPNCore/Configuration.swift b/Sources/TunnelKitOpenVPNCore/Configuration.swift index 4d2d0c4..61345a7 100644 --- a/Sources/TunnelKitOpenVPNCore/Configuration.swift +++ b/Sources/TunnelKitOpenVPNCore/Configuration.swift @@ -51,7 +51,6 @@ extension OpenVPN { /// The password. public let password: String - /// :nodoc public init(_ username: String, _ password: String) { self.username = username self.password = password @@ -355,16 +354,14 @@ extension OpenVPN { /// The immutable configuration for `OpenVPNSession`. public struct Configuration: Codable, Equatable { - - /// :nodoc: - public struct Fallback { - public static let cipher: Cipher = .aes128cbc + struct Fallback { + static let cipher: Cipher = .aes128cbc - public static let digest: Digest = .sha1 + static let digest: Digest = .sha1 - public static let compressionFraming: CompressionFraming = .disabled + static let compressionFraming: CompressionFraming = .disabled - public static let compressionAlgorithm: CompressionAlgorithm = .disabled + static let compressionAlgorithm: CompressionAlgorithm = .disabled } /// - Seealso: `ConfigurationBuilder.cipher` diff --git a/Sources/TunnelKitOpenVPNCore/ConfigurationParser.swift b/Sources/TunnelKitOpenVPNCore/ConfigurationParser.swift index 20d1dad..04f5581 100644 --- a/Sources/TunnelKitOpenVPNCore/ConfigurationParser.swift +++ b/Sources/TunnelKitOpenVPNCore/ConfigurationParser.swift @@ -38,6 +38,7 @@ extension OpenVPN { // XXX: parsing is very optimistic + /// Regexes used to parse OpenVPN options. public struct Regex { // MARK: General diff --git a/Sources/TunnelKitOpenVPNManager/OpenVPN+ProviderConfiguration.swift b/Sources/TunnelKitOpenVPNManager/OpenVPN+ProviderConfiguration.swift index ffab605..a37b758 100644 --- a/Sources/TunnelKitOpenVPNManager/OpenVPN+ProviderConfiguration.swift +++ b/Sources/TunnelKitOpenVPNManager/OpenVPN+ProviderConfiguration.swift @@ -74,15 +74,13 @@ extension OpenVPN { /// Mask private data in debug log (default is `true`). public var masksPrivateData = true - /// :nodoc: - public init(_ title: String, appGroup: String, configuration: OpenVPN.Configuration) { + public init(_ title: String, appGroup: String, configuration: OpenVPN.Configuration) { self.title = title self.appGroup = appGroup self.configuration = configuration } - /// :nodoc: - public func print() { + public func print() { if let versionIdentifier = versionIdentifier { log.info("Tunnel version: \(versionIdentifier)") } @@ -97,8 +95,7 @@ extension OpenVPN { extension OpenVPN.ProviderConfiguration: NetworkExtensionConfiguration { - /// :nodoc: - public func asTunnelProtocol( + public func asTunnelProtocol( withBundleIdentifier tunnelBundleIdentifier: String, extra: NetworkExtensionExtra? ) throws -> NETunnelProviderProtocol { @@ -156,7 +153,6 @@ extension OpenVPN.ProviderConfiguration { } } -/// :nodoc: extension OpenVPN.ProviderConfiguration { public func _appexSetDataCount(_ newValue: DataCount?) { defaults?.openVPNDataCount = newValue @@ -183,7 +179,6 @@ extension OpenVPN.ProviderConfiguration { } } -/// :nodoc: extension UserDefaults { public func openVPNURLForDebugLog(appGroup: String) -> URL? { guard let path = string(forKey: OpenVPN.ProviderConfiguration.Keys.logPath.rawValue) else { diff --git a/Sources/TunnelKitWireGuardManager/WireGuard+ProviderConfiguration.swift b/Sources/TunnelKitWireGuardManager/WireGuard+ProviderConfiguration.swift index d025b61..380b559 100644 --- a/Sources/TunnelKitWireGuardManager/WireGuard+ProviderConfiguration.swift +++ b/Sources/TunnelKitWireGuardManager/WireGuard+ProviderConfiguration.swift @@ -73,8 +73,7 @@ extension WireGuard { extension WireGuard.ProviderConfiguration: NetworkExtensionConfiguration { - /// :nodoc: - public func asTunnelProtocol( + public func asTunnelProtocol( withBundleIdentifier tunnelBundleIdentifier: String, extra: NetworkExtensionExtra? ) throws -> NETunnelProviderProtocol { @@ -105,7 +104,6 @@ extension WireGuard.ProviderConfiguration { } } -/// :nodoc: extension WireGuard.ProviderConfiguration { public func _appexSetLastError(_ newValue: WireGuardProviderError?) { defaults?.wireGuardLastError = newValue @@ -124,7 +122,6 @@ extension WireGuard.ProviderConfiguration { } } -/// :nodoc: extension UserDefaults { public func wireGuardURLForDebugLog(appGroup: String) -> URL? { guard let path = string(forKey: WireGuard.ProviderConfiguration.Keys.logPath.rawValue) else {