Merge branch 'types-docs'

11 files changed, 72 insertions, 19 deletions

diff --git a/mullvad-types/src/account.rs b/mullvad-types/src/account.rs
index a725db13ee..67fb6ce2d0 100644
--- a/mullvad-types/src/account.rs
+++ b/mullvad-types/src/account.rs
@@ -3,8 +3,10 @@ use chrono::{offset::Utc, DateTime};
 use jnix::IntoJava;
 use serde::{Deserialize, Serialize};
 
+/// Identifier used to authenticate or identify a Mullvad account.
 pub type AccountToken = String;
 
+/// Account expiration info returned by the API via `/v1/me`.
 #[derive(Debug, Clone, Eq, PartialEq, Hash, Serialize, Deserialize)]
 #[cfg_attr(target_os = "android", derive(IntoJava))]
 #[cfg_attr(target_os = "android", jnix(package = "net.mullvad.mullvadvpn.model"))]
@@ -13,8 +15,8 @@ pub struct AccountData {
     pub expiry: DateTime<Utc>,
 }
 
-/// Data-structure that's returned from successfuly invocation of the mullvad API's
-/// `submit_voucher(account, voucher)` RPC
+/// Data structure that's returned from successful invocation of the mullvad API's
+/// `/v1/submit-voucher` RPC.
 #[derive(serde::Deserialize, serde::Serialize, Debug)]
 pub struct VoucherSubmission {
     /// Amount of time added to the account
@@ -23,7 +25,8 @@ pub struct VoucherSubmission {
     pub new_expiry: DateTime<Utc>,
 }
 
-/// Mapping of mullvad-api errors
+/// Mapping of mullvad-api errors to enum variants. Used by frontends to explain why a voucher
+/// was rejected by the `/v1/submit-voucher` RPC.
 #[derive(err_derive::Error, Debug)]
 pub enum VoucherError {
     /// Error code -400
diff --git a/mullvad-types/src/auth_failed.rs b/mullvad-types/src/auth_failed.rs
index 4fcfe66463..fd8ff2b7b5 100644
--- a/mullvad-types/src/auth_failed.rs
+++ b/mullvad-types/src/auth_failed.rs
@@ -2,6 +2,9 @@ use lazy_static::lazy_static;
 use regex::Regex;
 use std::fmt;
 
+/// Used by frontends to parse [`talpid_types::tunnel::ErrorStateCause::AuthFailed`], which may be
+/// returned in [`talpid_types::tunnel::ErrorStateCause`] when there is a failure to authenticate
+/// with a remote server.
 #[derive(Debug)]
 pub struct AuthFailed {
     reason: AuthFailedInner,
diff --git a/mullvad-types/src/location.rs b/mullvad-types/src/location.rs
index 07a0c00795..243c0768e8 100644
--- a/mullvad-types/src/location.rs
+++ b/mullvad-types/src/location.rs
@@ -7,6 +7,7 @@ pub type CountryCode = String;
 pub type CityCode = String;
 pub type Hostname = String;
 
+/// Describes the physical location of a [`crate::relay_list::Relay`] as returned by the API.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Location {
     pub country: String,
diff --git a/mullvad-types/src/relay_constraints.rs b/mullvad-types/src/relay_constraints.rs
index bc99c6f862..fcf81daede 100644
--- a/mullvad-types/src/relay_constraints.rs
+++ b/mullvad-types/src/relay_constraints.rs
@@ -17,6 +17,7 @@ pub trait Match<T> {
     fn matches(&self, other: &T) -> bool;
 }
 
+/// Limits the set of [`crate::relay_list::Relay`]s that a `RelaySelector` may select.
 #[derive(Debug, Clone, Eq, PartialEq, Deserialize, Serialize)]
 #[serde(rename_all = "snake_case")]
 #[cfg_attr(target_os = "android", derive(FromJava, IntoJava))]
@@ -66,6 +67,8 @@ impl<T: fmt::Debug + Clone + Eq + PartialEq> Match<T> for Constraint<T> {
     }
 }
 
+/// Specifies a specific endpoint or [`RelayConstraints`] to use when `mullvad-daemon` selects a
+/// relay.
 #[derive(Debug, Clone, Eq, PartialEq, Deserialize, Serialize)]
 #[serde(rename_all = "snake_case")]
 #[cfg_attr(target_os = "android", derive(IntoJava))]
@@ -127,6 +130,7 @@ impl RelaySettings {
     }
 }
 
+/// Limits the set of [`crate::relay_list::Relay`]s that a `RelaySelector` may select.
 #[derive(Debug, Clone, Eq, PartialEq, Deserialize, Serialize)]
 #[cfg_attr(not(target_os = "android"), derive(Default))]
 #[cfg_attr(target_os = "android", derive(IntoJava))]
@@ -199,6 +203,8 @@ impl fmt::Display for RelayConstraints {
 }
 
 
+/// Limits the set of [`crate::relay_list::Relay`]s used by a `RelaySelector` based on
+/// location.
 #[derive(Debug, Clone, Eq, PartialEq, Deserialize, Serialize)]
 #[serde(rename_all = "snake_case")]
 #[cfg_attr(target_os = "android", derive(FromJava, IntoJava))]
@@ -224,6 +230,7 @@ impl fmt::Display for LocationConstraint {
     }
 }
 
+/// Used in [`RelayConstraints`] to limit relay selection based on protocol.
 #[derive(Debug, Clone, Eq, PartialEq, Deserialize, Serialize)]
 pub enum TunnelProtocol {
     #[serde(rename = "wireguard")]
@@ -241,6 +248,7 @@ impl fmt::Display for TunnelProtocol {
     }
 }
 
+/// Deprecated. Contains protocol-specific constraints for relay selection.
 #[derive(Debug, Clone, Eq, PartialEq, Deserialize, Serialize)]
 pub enum TunnelConstraints {
     #[serde(rename = "openvpn")]
@@ -282,6 +290,7 @@ impl Match<WireguardEndpointData> for TunnelConstraints {
     }
 }
 
+/// [`Constraint`]s applicable to OpenVPN relay servers.
 #[derive(Debug, Default, Copy, Clone, Eq, PartialEq, Deserialize, Serialize)]
 pub struct OpenVpnConstraints {
     pub port: Constraint<u16>,
@@ -308,6 +317,7 @@ impl Match<OpenVpnEndpointData> for OpenVpnConstraints {
     }
 }
 
+/// [`Constraint`]s applicable to WireGuard relay servers.
 #[derive(Debug, Default, Copy, Clone, Eq, PartialEq, Deserialize, Serialize)]
 pub struct WireguardConstraints {
     pub port: Constraint<u16>,
@@ -335,6 +345,8 @@ impl Match<WireguardEndpointData> for WireguardConstraints {
 }
 
 
+/// Specifies a specific endpoint or [`BridgeConstraints`] to use when `mullvad-daemon` selects a
+/// bridge server.
 #[derive(Debug, Clone, Eq, PartialEq, Deserialize, Serialize)]
 #[serde(rename_all = "snake_case")]
 pub enum BridgeSettings {
@@ -344,6 +356,7 @@ pub enum BridgeSettings {
 }
 
 
+/// Limits the set of bridge servers to use in `mullvad-daemon`.
 #[derive(Debug, Clone, Eq, PartialEq, Deserialize, Serialize)]
 #[serde(rename_all = "snake_case")]
 pub struct BridgeConstraints {
@@ -359,6 +372,7 @@ impl fmt::Display for BridgeConstraints {
     }
 }
 
+/// Setting indicating whether to connect to a bridge server, or to handle it automatically.
 #[derive(Debug, Clone, Eq, PartialEq, Deserialize, Serialize)]
 #[serde(rename_all = "snake_case")]
 pub enum BridgeState {
@@ -387,6 +401,7 @@ pub struct InternalBridgeConstraints {
     pub transport_protocol: Constraint<TransportProtocol>,
 }
 
+/// Used to update the [`RelaySettings`] used in `mullvad-daemon`.
 #[derive(Debug, Deserialize, Serialize)]
 #[cfg_attr(target_os = "android", derive(FromJava))]
 #[cfg_attr(target_os = "android", jnix(package = "net.mullvad.mullvadvpn.model"))]
@@ -422,6 +437,7 @@ impl RelaySettingsUpdate {
     }
 }
 
+/// Used in [`RelaySettings`] to change relay constraints in the daemon.
 #[derive(Debug, Default, Deserialize, Serialize)]
 #[cfg_attr(target_os = "android", derive(FromJava))]
 #[cfg_attr(target_os = "android", jnix(package = "net.mullvad.mullvadvpn.model"))]
diff --git a/mullvad-types/src/relay_list.rs b/mullvad-types/src/relay_list.rs
index 7277b922ca..c3bbc33b6f 100644
--- a/mullvad-types/src/relay_list.rs
+++ b/mullvad-types/src/relay_list.rs
@@ -15,6 +15,8 @@ use talpid_types::net::{
 };
 
 
+/// Stores a list of relays for each country obtained from the API using
+/// `mullvad_rpc::RelayListProxy`. This can also be passed to frontends.
 #[derive(Debug, Clone, Deserialize, Serialize)]
 #[cfg_attr(target_os = "android", derive(IntoJava))]
 #[cfg_attr(target_os = "android", jnix(package = "net.mullvad.mullvadvpn.model"))]
@@ -30,6 +32,7 @@ impl RelayList {
     }
 }
 
+/// A list of [`RelayListCity`]s within a country. Used by [`RelayList`].
 #[derive(Debug, Clone, Deserialize, Serialize)]
 #[cfg_attr(target_os = "android", derive(IntoJava))]
 #[cfg_attr(target_os = "android", jnix(package = "net.mullvad.mullvadvpn.model"))]
@@ -39,6 +42,7 @@ pub struct RelayListCountry {
     pub cities: Vec<RelayListCity>,
 }
 
+/// A list of [`Relay`]s within a city. Used by [`RelayListCountry`].
 #[derive(Debug, Clone, Deserialize, Serialize)]
 #[cfg_attr(target_os = "android", derive(IntoJava))]
 #[cfg_attr(target_os = "android", jnix(package = "net.mullvad.mullvadvpn.model"))]
@@ -52,6 +56,8 @@ pub struct RelayListCity {
     pub relays: Vec<Relay>,
 }
 
+/// Stores information for a relay returned by the API at `v1/relays` using
+/// `mullvad_rpc::RelayListProxy`.
 #[derive(Debug, Clone, Deserialize, Serialize)]
 #[cfg_attr(target_os = "android", derive(IntoJava))]
 #[cfg_attr(target_os = "android", jnix(package = "net.mullvad.mullvadvpn.model"))]
@@ -79,6 +85,7 @@ pub struct Relay {
     pub location: Option<Location>,
 }
 
+/// Provides protocol-specific information about a [`Relay`].
 #[derive(Debug, Default, Clone, Deserialize, Serialize)]
 #[serde(default)]
 #[cfg_attr(target_os = "android", derive(IntoJava))]
@@ -100,6 +107,7 @@ impl RelayTunnels {
     }
 }
 
+/// Data needed to connect to an OpenVPN endpoint at a [`Relay`].
 #[derive(Debug, Copy, Clone, Eq, PartialEq, Hash, Deserialize, Serialize)]
 pub struct OpenVpnEndpointData {
     pub port: u16,
@@ -118,6 +126,7 @@ impl fmt::Display for OpenVpnEndpointData {
     }
 }
 
+/// Data needed to connect to a WireGuard endpoint at a [`Relay`].
 #[derive(Clone, Eq, PartialEq, Hash, Deserialize, Serialize, Debug)]
 #[cfg_attr(target_os = "android", derive(IntoJava))]
 #[cfg_attr(target_os = "android", jnix(package = "net.mullvad.mullvadvpn.model"))]
@@ -149,6 +158,7 @@ impl fmt::Display for WireguardEndpointData {
     }
 }
 
+/// Used by `mullvad_rpc::RelayListProxy` to store bridge servers for a [`Relay`].
 #[derive(Debug, Default, Clone, Deserialize, Serialize)]
 #[serde(default)]
 pub struct RelayBridges {
@@ -165,6 +175,7 @@ impl RelayBridges {
     }
 }
 
+/// Data needed to connect to a Shadowsocks endpoint at a [`Relay`].
 #[derive(Debug, Clone, Eq, PartialEq, Hash, Deserialize, Serialize)]
 pub struct ShadowsocksEndpointData {
     pub port: u16,
diff --git a/talpid-types/src/lib.rs b/talpid-types/src/lib.rs
index d333ecca91..d5b71fd46d 100644
--- a/talpid-types/src/lib.rs
+++ b/talpid-types/src/lib.rs
@@ -8,6 +8,7 @@ pub mod net;
 pub mod tunnel;
 
 
+/// Used to generate string representations of error chains.
 pub trait ErrorExt {
     /// Creates a string representation of the entire error chain.
     fn display_chain(&self) -> String;
diff --git a/talpid-types/src/net/mod.rs b/talpid-types/src/net/mod.rs
index bcfec414ae..97292fd381 100644
--- a/talpid-types/src/net/mod.rs
+++ b/talpid-types/src/net/mod.rs
@@ -57,7 +57,7 @@ impl From<openvpn::TunnelParameters> for TunnelParameters {
     }
 }
 
-/// Type of the tunnel
+/// The tunnel protocol used by a [`TunnelEndpoint`].
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
 #[serde(rename = "tunnel_type")]
 pub enum TunnelType {
@@ -85,7 +85,6 @@ impl fmt::Display for TunnelType {
 pub struct TunnelEndpoint {
     #[serde(flatten)]
     pub endpoint: Endpoint,
-    /// Type of the tunnel
     #[cfg_attr(target_os = "android", jnix(skip))]
     pub tunnel_type: TunnelType,
     #[cfg_attr(target_os = "android", jnix(skip))]
@@ -167,6 +166,9 @@ impl fmt::Display for TransportProtocol {
     }
 }
 
+
+/// Returned when `TransportProtocol::from_str` fails to convert a string into a
+/// [`TransportProtocol`] object.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct TransportProtocolParseError;
 
@@ -184,7 +186,9 @@ pub struct GenericTunnelOptions {
     pub enable_ipv6: bool,
 }
 
-/// Returns a vector of IP networks representing all of the internet.
+/// Returns a vector of IP networks representing all of the internet, 0.0.0.0/0.
+/// This may be used in [`crate::net::wireguard::PeerConfig`] to route all traffic
+/// to the tunnel interface.
 pub fn all_of_the_internet() -> Vec<ipnetwork::IpNetwork> {
     vec![
         "0.0.0.0/0".parse().expect("Failed to parse ipv6 network"),
diff --git a/talpid-types/src/net/openvpn.rs b/talpid-types/src/net/openvpn.rs
index d9c31ed92b..c7beed6559 100644
--- a/talpid-types/src/net/openvpn.rs
+++ b/talpid-types/src/net/openvpn.rs
@@ -5,6 +5,8 @@ use crate::net::{
 use serde::{Deserialize, Serialize};
 use std::net::SocketAddr;
 
+/// Information needed by `OpenVpnMonitor` to establish a tunnel connection.
+/// See [`crate::net::TunnelParameters`].
 #[derive(Debug, Clone, Eq, PartialEq, Hash, Deserialize, Serialize)]
 pub struct TunnelParameters {
     pub config: ConnectionConfig,
@@ -13,6 +15,7 @@ pub struct TunnelParameters {
     pub proxy: Option<ProxySettings>,
 }
 
+/// Connection configuration used by [`TunnelParameters`].
 #[derive(Debug, Clone, Eq, PartialEq, Hash, Deserialize, Serialize)]
 pub struct ConnectionConfig {
     pub endpoint: Endpoint,
@@ -30,9 +33,10 @@ impl ConnectionConfig {
     }
 }
 
-/// TunnelOptions contains options for an openvpn tunnel that should be applied
+/// `TunnelOptions` contains options for an OpenVPN tunnel that should be applied
 /// irrespective of the relay parameters - i.e. have nothing to do with the particular
 /// OpenVPN server, but do affect the connection.
+/// Stored in [`TunnelParameters`].
 #[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize, Default)]
 pub struct TunnelOptions {
     /// Optional argument for openvpn to try and limit TCP packet size,
@@ -40,14 +44,12 @@ pub struct TunnelOptions {
     pub mssfix: Option<u16>,
 }
 
+/// Proxy server options to be used by `OpenVpnMonitor` when starting a tunnel.
 #[derive(Debug, Clone, PartialEq, Eq, Hash, Deserialize, Serialize)]
 #[serde(rename_all = "snake_case")]
 pub enum ProxySettings {
-    /// Generic proxy running independently on localhost.
     Local(LocalProxySettings),
-    /// Generic proxy running on remote host.
     Remote(RemoteProxySettings),
-    /// Bundled Shadowsocks proxy.
     Shadowsocks(ShadowsocksProxySettings),
 }
 
@@ -71,6 +73,7 @@ impl ProxySettings {
     }
 }
 
+/// Options for a generic proxy running on localhost.
 #[derive(Debug, Clone, Eq, PartialEq, Hash, Deserialize, Serialize)]
 pub struct LocalProxySettings {
     pub port: u16,
@@ -86,6 +89,7 @@ impl LocalProxySettings {
     }
 }
 
+/// Options for a generic proxy running on remote host.
 #[derive(Debug, Clone, Eq, PartialEq, Hash, Deserialize, Serialize)]
 pub struct RemoteProxySettings {
     pub address: SocketAddr,
@@ -107,6 +111,7 @@ pub struct ProxyAuth {
     pub password: String,
 }
 
+/// Options for a bundled Shadowsocks proxy.
 #[derive(Debug, Clone, Eq, PartialEq, Hash, Deserialize, Serialize)]
 pub struct ShadowsocksProxySettings {
     pub peer: SocketAddr,
@@ -124,6 +129,8 @@ impl ShadowsocksProxySettings {
     }
 }
 
+/// List of ciphers usable by a Shadowsocks proxy.
+/// Cf. [`ShadowsocksProxySettings::cipher`].
 pub static SHADOWSOCKS_CIPHERS: &[&str] = &[
     // Stream ciphers.
     "aes-128-cfb",
@@ -148,6 +155,7 @@ pub static SHADOWSOCKS_CIPHERS: &[&str] = &[
     "aes-256-pmac-siv",
 ];
 
+/// Checks whether the proxy settings to be used by `OpenVpnMonitor` are valid.
 pub fn validate_proxy_settings(proxy: &ProxySettings) -> Result<(), String> {
     match proxy {
         ProxySettings::Local(local) => {
diff --git a/talpid-types/src/net/proxy.rs b/talpid-types/src/net/proxy.rs
index d2960932c6..73e87915c4 100644
--- a/talpid-types/src/net/proxy.rs
+++ b/talpid-types/src/net/proxy.rs
@@ -6,9 +6,7 @@ use std::fmt;
 #[serde(rename_all = "snake_case")]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub enum ProxyType {
-    /// Shadowsocks
     Shadowsocks,
-    /// Custom bridge
     Custom,
 }
 
@@ -23,7 +21,7 @@ impl fmt::Display for ProxyType {
 }
 
 
-/// Bridge endpoint, broadcast as part of TunnelEndpoint
+/// Bridge endpoint, broadcast as part of a [`crate::net::TunnelEndpoint`].
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub struct ProxyEndpoint {
     #[serde(flatten)]
diff --git a/talpid-types/src/net/wireguard.rs b/talpid-types/src/net/wireguard.rs
index 9e6e6290bd..0433179880 100644
--- a/talpid-types/src/net/wireguard.rs
+++ b/talpid-types/src/net/wireguard.rs
@@ -11,18 +11,21 @@ use std::{
 };
 
 
+/// Tunnel parameters required to start a `WireguardMonitor`.
+/// See [`crate::net::TunnelParameters`].
 #[derive(Clone, Eq, PartialEq, Deserialize, Serialize, Debug)]
-/// Wireguard tunnel parameters
 pub struct TunnelParameters {
     pub connection: ConnectionConfig,
     pub options: TunnelOptions,
     pub generic_options: GenericTunnelOptions,
 }
 
+/// Connection-specific configuration in [`TunnelParameters`].
 #[derive(Clone, Debug, Eq, PartialEq, Deserialize, Serialize)]
 pub struct ConnectionConfig {
     pub tunnel: TunnelConfig,
     pub peer: PeerConfig,
+    /// Gateway used by the tunnel (a private address).
     pub ipv4_gateway: Ipv4Addr,
     pub ipv6_gateway: Option<Ipv6Addr>,
 }
@@ -38,18 +41,22 @@ impl ConnectionConfig {
 
 #[derive(Clone, Eq, PartialEq, Deserialize, Serialize, Debug, Hash)]
 pub struct PeerConfig {
+    /// Public key corresponding to the private key in [`TunnelConfig`].
     pub public_key: PublicKey,
+    /// Addresses that may be routed to the peer. Use `0.0.0.0/0` to route everything.
     pub allowed_ips: Vec<IpNetwork>,
+    /// IP address of the WireGuard server.
     pub endpoint: SocketAddr,
 }
 
 #[derive(Clone, Eq, PartialEq, Deserialize, Serialize, Debug)]
 pub struct TunnelConfig {
     pub private_key: PrivateKey,
+    /// Local IP addresses associated with a key pair.
     pub addresses: Vec<IpAddr>,
 }
 
-/// Wireguard tunnel options
+/// Options in [`TunnelParameters`] that apply to any WireGuard connection.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[cfg_attr(target_os = "android", derive(IntoJava))]
 #[cfg_attr(
diff --git a/talpid-types/src/tunnel.rs b/talpid-types/src/tunnel.rs
index a921d1ba0c..dda152d3f1 100644
--- a/talpid-types/src/tunnel.rs
+++ b/talpid-types/src/tunnel.rs
@@ -4,7 +4,8 @@ use jnix::IntoJava;
 use serde::{Deserialize, Serialize};
 use std::fmt;
 
-/// Event resulting from a transition to a new tunnel state.
+/// Event emitted from the states in `talpid_core::tunnel_state_machine` when the tunnel state
+/// machine enters a new state.
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case")]
 #[serde(tag = "state", content = "details")]
@@ -17,7 +18,7 @@ pub enum TunnelStateTransition {
     Connected(TunnelEndpoint),
     /// Disconnecting tunnel.
     Disconnecting(ActionAfterDisconnect),
-    /// Tunnel is disconnected but secured by blocking all connections.
+    /// Tunnel is disconnected but usually secured by blocking all connections.
     Error(ErrorState),
 }
 
@@ -32,7 +33,7 @@ pub enum ActionAfterDisconnect {
     Reconnect,
 }
 
-/// Error state
+/// Represents the tunnel state machine entering an error state during a [`TunnelStateTransition`].
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case")]
 #[cfg_attr(target_os = "android", derive(IntoJava))]
@@ -62,7 +63,7 @@ impl ErrorState {
 }
 
 
-/// Reason for entering the blocked state.
+/// Reason for the tunnel state machine entering an [`ErrorState`].
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case")]
 #[serde(tag = "reason", content = "details")]