Add more documentation

swift/apple/FirezoneNetworkExtension/Adapter.swift

@@ -234,10 +234,11 @@ extension Adapter {
   /// - System DNS servers change, including when we set them
   /// - Routes change, including when we set them
   ///
-  /// Apple doesn't give us very much info this callback, so we don't know which of the two
+  /// Apple doesn't give us very much info in this callback, so we don't know which of the
   /// events above triggered the callback.
   ///
   /// On iOS this creates a problem:
+  ///
   /// We have no good way to get the System's default resolvers. We use a workaround which
   /// involves reading the resolvers from Bind (i.e. /etc/resolv.conf) but this will be set to connlib's
   /// DNS sentinel while the tunnel is active, which isn't helpful to us. To get around this, we can
@@ -247,6 +248,16 @@ extension Adapter {
   /// differentiate between us changing the DNS configuration and the system actually receiving new
   /// default resolvers.
   ///
+  /// So we solve this problem by only doing this DNS dance if the gateways available to the path have
+  /// changed. This means we only call setDns when the physical network has changed, and therefore
+  /// we're blind to path updates where only the DNS resolvers have changed. That will happen in two
+  /// cases most commonly:
+  /// - New DNS servers were set by DHCP
+  /// - The user manually changed the DNS servers in the system settings
+  ///
+  /// For now, this will break DNS if the old servers connlib is using are no longer valid, and
+  /// can only be fixed with a sign out and sign back in which restarts the NetworkExtension.
+  ///
   /// On macOS, Apple has exposed the SystemConfiguration framework which makes this easy and
   /// doesn't suffer from this issue.
   ///