chore: Document everything (to a certain degree)

.gitignore

@@ -1,2 +1,3 @@
 .build/
 .vscode/launch.json
+.env

.swiftlint.yml

@@ -17,6 +17,19 @@ disabled_rules:
   - line_length
   # not a very useful lint honestly.
   - cyclomatic_complexity
+  # it's basically exclusively used for `unreachable`
+  - force_try
+  # This triggers a lot because of functions that simply cannot be smaller.
+  - function_body_length
+  # see above.
+  - closure_body_length
+  # And this triggers a lot because of the above two.
+  - type_body_length
+  # likewise here
+  - file_length
+  # Identifier names should make sense, 
+  # and renaming stuff isn't always the right decision.
+  - identifier_name
 
 opt_in_rules:
   # deprecated & will be removed
@@ -51,6 +64,7 @@ opt_in_rules:
   # - extension_access_modifier
   - fallthrough
   - fatal_error_message
+  - missing_docs
 
 analyzer_rules:
   - capture_variable

Examples/CreateAccount/main.swift

@@ -22,8 +22,8 @@ import Hedera
 import SwiftDotenv
 
 @main
-public enum Program {
-    public static func main() async throws {
+internal enum Program {
+    internal static func main() async throws {
         let env = try Dotenv.load()
         let client = try Client.forName(env.networkName)
 
@@ -47,15 +47,20 @@ public enum Program {
 }
 
 extension Environment {
-    public var operatorAccountId: AccountId {
+    /// Account ID for the operator to use in this example.
+    internal var operatorAccountId: AccountId {
         AccountId(self["OPERATOR_ACCOUNT_ID"]!.stringValue)!
     }
 
-    public var operatorKey: PrivateKey {
+    /// Private key for the operator to use in this example.
+    internal var operatorKey: PrivateKey {
         PrivateKey(self["OPERATOR_KEY"]!.stringValue)!
     }
 
-    public var networkName: String {
+    /// The name of the hedera network this example should be ran against.
+    ///
+    /// Testnet by default.
+    internal var networkName: String {
         self["HEDERA_NETWORK"]?.stringValue ?? "testnet"
     }
 }

Examples/CreateFile/main.swift

@@ -22,8 +22,8 @@ import Hedera
 import SwiftDotenv
 
 @main
-public enum Program {
-    public static func main() async throws {
+internal enum Program {
+    internal static func main() async throws {
         let env = try Dotenv.load()
         let client = try Client.forName(env.networkName)
 
@@ -48,15 +48,20 @@ public enum Program {
 }
 
 extension Environment {
-    public var operatorAccountId: AccountId {
+    /// Account ID for the operator to use in this example.
+    internal var operatorAccountId: AccountId {
         AccountId(self["OPERATOR_ACCOUNT_ID"]!.stringValue)!
     }
 
-    public var operatorKey: PrivateKey {
+    /// Private key for the operator to use in this example.
+    internal var operatorKey: PrivateKey {
         PrivateKey(self["OPERATOR_KEY"]!.stringValue)!
     }
 
-    public var networkName: String {
+    /// The name of the hedera network this example should be ran against.
+    ///
+    /// Testnet by default.
+    internal var networkName: String {
         self["HEDERA_NETWORK"]?.stringValue ?? "testnet"
     }
 }

Examples/CreateTopic/main.swift

@@ -22,8 +22,8 @@ import Hedera
 import SwiftDotenv
 
 @main
-public enum Program {
-    public static func main() async throws {
+internal enum Program {
+    internal static func main() async throws {
         let env = try Dotenv.load()
         let client = try Client.forName(env.networkName)
 
@@ -46,16 +46,22 @@ public enum Program {
         print("sequence number = \(sendReceipt.topicSequenceNumber)")
     }
 }
+
 extension Environment {
-    public var operatorAccountId: AccountId {
+    /// Account ID for the operator to use in this example.
+    internal var operatorAccountId: AccountId {
         AccountId(self["OPERATOR_ACCOUNT_ID"]!.stringValue)!
     }
 
-    public var operatorKey: PrivateKey {
+    /// Private key for the operator to use in this example.
+    internal var operatorKey: PrivateKey {
         PrivateKey(self["OPERATOR_KEY"]!.stringValue)!
     }
 
-    public var networkName: String {
+    /// The name of the hedera network this example should be ran against.
+    ///
+    /// Testnet by default.
+    internal var networkName: String {
         self["HEDERA_NETWORK"]?.stringValue ?? "testnet"
     }
 }

Examples/DeleteAccount/main.swift

@@ -22,8 +22,8 @@ import Hedera
 import SwiftDotenv
 
 @main
-public enum Program {
-    public static func main() async throws {
+internal enum Program {
+    internal static func main() async throws {
         let env = try Dotenv.load()
         let client = try Client.forName(env.networkName)
 
@@ -39,15 +39,20 @@ public enum Program {
 }
 
 extension Environment {
+    /// Account ID for the operator to use in this example.
     internal var operatorAccountId: AccountId {
         AccountId(self["OPERATOR_ACCOUNT_ID"]!.stringValue)!
     }
 
+    /// Private key for the operator to use in this example.
     internal var operatorKey: PrivateKey {
         PrivateKey(self["OPERATOR_KEY"]!.stringValue)!
     }
 
-    public var networkName: String {
+    /// The name of the hedera network this example should be ran against.
+    ///
+    /// Testnet by default.
+    internal var networkName: String {
         self["HEDERA_NETWORK"]?.stringValue ?? "testnet"
     }
 }

Examples/DeleteFile/main.swift

@@ -22,8 +22,8 @@ import Hedera
 import SwiftDotenv
 
 @main
-public enum Program {
-    public static func main() async throws {
+internal enum Program {
+    internal static func main() async throws {
         let env = try Dotenv.load()
         let client = try Client.forName(env.networkName)
 
@@ -52,15 +52,20 @@ public enum Program {
 }
 
 extension Environment {
-    public var operatorAccountId: AccountId {
+    /// Account ID for the operator to use in this example.
+    internal var operatorAccountId: AccountId {
         AccountId(self["OPERATOR_ACCOUNT_ID"]!.stringValue)!
     }
 
-    public var operatorKey: PrivateKey {
+    /// Private key for the operator to use in this example.
+    internal var operatorKey: PrivateKey {
         PrivateKey(self["OPERATOR_KEY"]!.stringValue)!
     }
 
-    public var networkName: String {
+    /// The name of the hedera network this example should be ran against.
+    ///
+    /// Testnet by default.
+    internal var networkName: String {
         self["HEDERA_NETWORK"]?.stringValue ?? "testnet"
     }
 }

Examples/FileAppendChunked/main.swift

@@ -51,8 +51,8 @@ private let bigContents = """
     """
 
 @main
-public enum Program {
-    public static func main() async throws {
+internal enum Program {
+    internal static func main() async throws {
         let env = try Dotenv.load()
         let client = try Client.forName(env.networkName)
 
@@ -88,15 +88,20 @@ public enum Program {
 }
 
 extension Environment {
+    /// Account ID for the operator to use in this example.
     internal var operatorAccountId: AccountId {
         AccountId(self["OPERATOR_ACCOUNT_ID"]!.stringValue)!
     }
 
+    /// Private key for the operator to use in this example.
     internal var operatorKey: PrivateKey {
         PrivateKey(self["OPERATOR_KEY"]!.stringValue)!
     }
 
-    public var networkName: String {
+    /// The name of the hedera network this example should be ran against.
+    ///
+    /// Testnet by default.
+    internal var networkName: String {
         self["HEDERA_NETWORK"]?.stringValue ?? "testnet"
     }
 }

Examples/GenerateKey/main.swift

@@ -22,8 +22,8 @@ import Foundation
 import Hedera
 
 @main
-public enum Program {
-    public static func main() async throws {
+internal enum Program {
+    internal static func main() async throws {
         // Generate a Ed25519 key
         // This is the current recommended default for Hedera
 

Examples/GenerateKeyWithMnemonic/main.swift

@@ -22,8 +22,8 @@ import Foundation
 import Hedera
 
 @main
-public enum Program {
-    public static func main() async throws {
+internal enum Program {
+    internal static func main() async throws {
         do {
             let mnemonic = Mnemonic.generate24()
             let privateKey = try mnemonic.toPrivateKey()

Examples/GetAccountBalance/main.swift

@@ -22,8 +22,8 @@ import Hedera
 import SwiftDotenv
 
 @main
-public enum Program {
-    public static func main() async throws {
+internal enum Program {
+    internal static func main() async throws {
         let env = try Dotenv.load()
         let client = try Client.forName(env.networkName)
 
@@ -38,7 +38,10 @@ public enum Program {
 }
 
 extension Environment {
-    public var networkName: String {
+    /// The name of the hedera network this example should be ran against.
+    ///
+    /// Testnet by default.
+    internal var networkName: String {
         self["HEDERA_NETWORK"]?.stringValue ?? "testnet"
     }
 }

Examples/GetAccountInfo/main.swift

@@ -22,8 +22,8 @@ import Hedera
 import SwiftDotenv
 
 @main
-public enum Program {
-    public static func main() async throws {
+internal enum Program {
+    internal static func main() async throws {
         let env = try Dotenv.load()
         let client = try Client.forName(env.networkName)
 
@@ -40,15 +40,20 @@ public enum Program {
 }
 
 extension Environment {
+    /// Account ID for the operator to use in this example.
     internal var operatorAccountId: AccountId {
         AccountId(self["OPERATOR_ACCOUNT_ID"]!.stringValue)!
     }
 
+    /// Private key for the operator to use in this example.
     internal var operatorKey: PrivateKey {
         PrivateKey(self["OPERATOR_KEY"]!.stringValue)!
     }
 
-    public var networkName: String {
+    /// The name of the hedera network this example should be ran against.
+    ///
+    /// Testnet by default.
+    internal var networkName: String {
         self["HEDERA_NETWORK"]?.stringValue ?? "testnet"
     }
 }

Examples/GetAddressBook/main.swift

@@ -23,8 +23,8 @@ import Hedera
 import SwiftDotenv
 
 @main
-public enum Program {
-    public static func main() async throws {
+internal enum Program {
+    internal static func main() async throws {
         let env = try Dotenv.load()
         let client = try Client.forName(env.networkName)
 
@@ -39,7 +39,10 @@ public enum Program {
 }
 
 extension Environment {
-    public var networkName: String {
+    /// The name of the hedera network this example should be ran against.
+    ///
+    /// Testnet by default.
+    internal var networkName: String {
         self["HEDERA_NETWORK"]?.stringValue ?? "testnet"
     }
 }

Examples/GetExchangeRates/main.swift

@@ -22,8 +22,8 @@ import Hedera
 import SwiftDotenv
 
 @main
-public enum Program {
-    public static func main() async throws {
+internal enum Program {
+    internal static func main() async throws {
         let env = try Dotenv.load()
         let client = try Client.forName(env.networkName)
 
@@ -50,21 +50,27 @@ public enum Program {
 }
 
 extension Environment {
-    public var operatorAccountId: AccountId {
+    /// Account ID for the operator to use in this example.
+    internal var operatorAccountId: AccountId {
         AccountId(self["OPERATOR_ACCOUNT_ID"]!.stringValue)!
     }
 
-    public var operatorKey: PrivateKey {
+    /// Private key for the operator to use in this example.
+    internal var operatorKey: PrivateKey {
         PrivateKey(self["OPERATOR_KEY"]!.stringValue)!
     }
 
-    public var networkName: String {
+    /// The name of the hedera network this example should be ran against.
+    ///
+    /// Testnet by default.
+    internal var networkName: String {
         self["HEDERA_NETWORK"]?.stringValue ?? "testnet"
     }
 
+    /// The file ID for the exchange rates file.
+    ///
+    /// By default this is `FileId.exchangeRates`.
     public var exchangeRatesFile: FileId {
-        // we really do want to abort if the value is invalid
-        // swiftlint:disable:next force_try
         try! (self["HEDERA_EXCHANGE_RATES_FILE"]?.stringValue).map(FileId.fromString) ?? FileId.exchangeRates
     }
 }