Add some comments explaining how the world works.

Author: arik-so

ci/LDKSwift/Tests/LDKSwiftTests/HumanObjectPeerTestInstance.swift

@@ -303,7 +303,7 @@ public class HumanObjectPeerTestInstance {
 
                 let graph = NetworkGraph(network: .Regtest, logger: self.logger)
                 var scorerGraph = graph
-                if(master.configuration.ephemeralNetworkGraphForScorer) {
+                if master.configuration.ephemeralNetworkGraphForScorer {
                     scorerGraph = NetworkGraph(network: .Regtest, logger: self.logger)
                 }
 

ci/LDKSwift/Tests/LDKSwiftTests/LDKSwiftTests.swift

@@ -456,6 +456,10 @@ class LDKSwiftTests: XCTestCase {
             print("Running test with flags \(i)");
 
             let config = HumanObjectPeerTestInstance.Configuration()
+            
+            // We have a set of configuration properties. We run through all possible
+            // combinations, and set each individual property depending on whether
+            // its bit is set.
 
             config.shouldRecipientRejectPayment = (i & (1 << 0)) != 0
             print("shouldRecipientRejectPayment: \(config.shouldRecipientRejectPayment)")
@@ -469,26 +473,6 @@ class LDKSwiftTests: XCTestCase {
             config.ephemeralNetworkGraphForScorer = (i & (1 << 3)) != 0
             print("ephemeralNetworkGraphForScorer: \(config.ephemeralNetworkGraphForScorer)")
 
-            /*
-            config.nice_close = (i & (1 << 0)) != 0;
-            config.use_km_wrapper = (i & (1 << 1)) != 0;
-            config.use_manual_watch = (i & (1 << 2)) != 0;
-            config.reload_peers = (i & (1 << 3)) != 0;
-            config.break_cross_peer_refs = (i & (1 << 4)) != 0;
-            config.use_nio_peer_handler = true // (i & (1 << 5)) != 0;
-            config.useChannelManagerConstructor = true //  (i & (1 << 6)) != 0;
-
-            if (config.break_cross_peer_refs && !config.reload_peers) {
-				// There are no cross refs to break without reloading peers.
-				continue;
-			}
-
-            if (config.useChannelManagerConstructor && (config.use_manual_watch || !config.use_nio_peer_handler)) {
-				// ChannelManagerConstructor requires a ChainMonitor as the Watch and creates a NioPeerHandler for us.
-				continue;
-			}
-            */
-
             let instance = HumanObjectPeerTestInstance(configuration: config)
             await instance.testMessageHandling()
 		}

src/generation/base_type_generator.mts

@@ -815,6 +815,22 @@ export abstract class BaseTypeGenerator<Type extends RustType> {
 						}
 				`;
 
+				/**
+				 * When an argument is an asterisk-based pointer, we usually simply create the
+				 * pointer-related handling like we do above, and nothing beyond that. However,
+				 * when the method taking that pointer is a constructor, it is likely that the
+				 * pointed-to argument will need to live well beyond the conclusion of the method
+				 * call. Specifically, it is likely a requirement of the instantiated object
+				 * that the argument is kept around for as long as necessary. We do that by
+				 * tethering the argument to the returned object. It's nothing but a reference
+				 * that will have Swift delay deallocation.
+				 *
+				 * If the reference is an elided type, such as an array, a nullable, or a tuple,
+				 * we, for the time being, just pretend that no anchoring is necessary. In reality,
+				 * we simply haven't encountered such a case yet, and until we do, it's a bit too
+				 * complicated to handle, because doing it blindly will probably only lead us to
+				 * introduce some new memory bugs.
+				 */
 				if(memoryContext && memoryContext.isConstructor && (argument.type instanceof RustStruct || argument.type instanceof RustTaggedValueEnum || argument.type instanceof RustResult)){
 					preparedArgument.requiresAnchoring = true;
 				}
@@ -1298,7 +1314,11 @@ export interface PreparedArgument {
 	deferredCleanup: string
 
 	/**
-	 * If true (only applicable in constructors), add a `self.addAnchor` call after super.init()
+	 * If true (only applicable in constructors), add a `self.addAnchor` call after super.init().
+	 * For anchoring that doesn't immediately succeed object instantiation, or that can happen
+	 * outside the initializer method, we have other mechanisms. This particular mechanism is,
+	 * strictly speaking, somewhat of a workaround, but one that is necessary due to Swift's
+	 * constraints surrounding when calls to `self` can be made.
 	 */
 	requiresAnchoring: boolean
 }