Add some missing documentation

This commit is contained in:
Davide De Rosa 2022-09-23 21:45:04 +02:00
parent 000fde0aa2
commit 64b3fa47af
12 changed files with 48 additions and 34 deletions

View File

@ -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

View File

@ -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) {

View File

@ -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
}

View File

@ -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
}

View File

@ -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)

View File

@ -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)

View File

@ -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() {

View File

@ -85,6 +85,8 @@ public protocol VPN {
}
extension DispatchTimeInterval {
/// Returns self in nanoseconds.
public var nanoseconds: UInt64 {
switch self {
case .seconds(let sec):

View File

@ -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 {
struct Fallback {
static let cipher: Cipher = .aes128cbc
/// :nodoc:
public struct Fallback {
public static let cipher: Cipher = .aes128cbc
static let digest: Digest = .sha1
public static let digest: Digest = .sha1
static let compressionFraming: CompressionFraming = .disabled
public static let compressionFraming: CompressionFraming = .disabled
public static let compressionAlgorithm: CompressionAlgorithm = .disabled
static let compressionAlgorithm: CompressionAlgorithm = .disabled
}
/// - Seealso: `ConfigurationBuilder.cipher`

View File

@ -38,6 +38,7 @@ extension OpenVPN {
// XXX: parsing is very optimistic
/// Regexes used to parse OpenVPN options.
public struct Regex {
// MARK: General

View File

@ -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 {

View File

@ -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 {