From c0bd6b2848a535d4cf1410979e7c6ecc754c401b Mon Sep 17 00:00:00 2001
From: Bug Magnet <marco.nikic@mullvad.net>
Date: Mon, 11 Nov 2024 10:06:14 +0100
Subject: [PATCH] Improve rust documentation

---
 .../include/mullvad_rust_runtime.h                 |  9 +++++++++
 mullvad-encrypted-dns-proxy/src/config_resolver.rs |  4 ++--
 mullvad-encrypted-dns-proxy/src/state.rs           |  2 +-
 mullvad-ios/src/encrypted_dns_proxy.rs             | 14 ++++++++++++--
 4 files changed, 24 insertions(+), 5 deletions(-)

diff --git a/ios/MullvadRustRuntime/include/mullvad_rust_runtime.h b/ios/MullvadRustRuntime/include/mullvad_rust_runtime.h
index 6679a499ae61..7cf59bcbbe60 100644
--- a/ios/MullvadRustRuntime/include/mullvad_rust_runtime.h
+++ b/ios/MullvadRustRuntime/include/mullvad_rust_runtime.h
@@ -24,6 +24,15 @@ extern const uint16_t CONFIG_SERVICE_PORT;
 
 /**
  * Initializes a valid pointer to an instance of `EncryptedDnsProxyState`.
+ *
+ * # Safety
+ *
+ * * [domain_name] must not be non-null.
+ *
+ * * [domain_name] pointer must be [valid](core::ptr#safety)
+ *
+ * * The caller must ensure that the pointer to the [domain_name] string contains a nul terminator
+ *   at the end of the string.
  */
 struct EncryptedDnsProxyState *encrypted_dns_proxy_init(const char *domain_name);
 
diff --git a/mullvad-encrypted-dns-proxy/src/config_resolver.rs b/mullvad-encrypted-dns-proxy/src/config_resolver.rs
index 96aa64e938a2..82edd886f529 100644
--- a/mullvad-encrypted-dns-proxy/src/config_resolver.rs
+++ b/mullvad-encrypted-dns-proxy/src/config_resolver.rs
@@ -61,12 +61,12 @@ pub fn default_resolvers() -> Vec<Nameserver> {
     ]
 }
 
+/// Calls [resolve_configs] with a given `domain` using known DoH resolvers provided by [default_resolvers]
 pub async fn resolve_default_config(domain: &str) -> Result<Vec<config::ProxyConfig>, Error> {
-    // TODO: We should remove the default value here and just force the callers to provide a domain instead
     resolve_configs(&default_resolvers(), domain).await
 }
 
-/// Look up the `domain` towards the given `resolvers`, and try to deserialize all the returned
+/// Looks up the `domain` towards the given `resolvers`, and try to deserialize all the returned
 /// AAAA records into [`ProxyConfig`](config::ProxyConfig)s.
 pub async fn resolve_configs(
     resolvers: &[Nameserver],
diff --git a/mullvad-encrypted-dns-proxy/src/state.rs b/mullvad-encrypted-dns-proxy/src/state.rs
index 3d6a26a0ce09..8b6c3c988627 100644
--- a/mullvad-encrypted-dns-proxy/src/state.rs
+++ b/mullvad-encrypted-dns-proxy/src/state.rs
@@ -58,7 +58,7 @@ impl EncryptedDnsProxyState {
         Some(selected_config)
     }
 
-    /// Fetch a config, but error out only when no existing configuration was there.
+    /// Fetch a config from `domain`, but error out only when no existing configuration was there.
     pub async fn fetch_configs(&mut self, domain: &str) -> Result<(), FetchConfigError> {
         match resolve_default_config(domain).await {
             Ok(new_configs) => {
diff --git a/mullvad-ios/src/encrypted_dns_proxy.rs b/mullvad-ios/src/encrypted_dns_proxy.rs
index d371044d48d0..3c89faf89502 100644
--- a/mullvad-ios/src/encrypted_dns_proxy.rs
+++ b/mullvad-ios/src/encrypted_dns_proxy.rs
@@ -82,12 +82,22 @@ impl EncryptedDnsProxyState {
 }
 
 /// Initializes a valid pointer to an instance of `EncryptedDnsProxyState`.
+///
+/// # Safety
+///
+/// * [domain_name] must not be non-null.
+///
+/// * [domain_name] pointer must be [valid](core::ptr#safety)
+///
+/// * The caller must ensure that the pointer to the [domain_name] string contains a nul terminator
+///   at the end of the string.
 #[no_mangle]
 pub unsafe extern "C" fn encrypted_dns_proxy_init(
     domain_name: *const c_char,
 ) -> *mut EncryptedDnsProxyState {
-    let domain = unsafe {
-        let c_str = CStr::from_ptr(domain_name);
+    // SAFETY: domain_name points to a valid region of memory and contains a nul terminator.
+    let domain = {
+        let c_str = unsafe { CStr::from_ptr(domain_name) };
         String::from_utf8_lossy(c_str.to_bytes())
     };