From 141e2b9535017ed2acb504c5323e377990f82c50 Mon Sep 17 00:00:00 2001
From: Markus Pettersson <markus.pettersson@mullvad.net>
Date: Wed, 13 Mar 2024 16:15:46 +0100
Subject: [PATCH] Fix TODO

Add documentation to `parsed_relays.rs`
---
 .../src/relay_selector/parsed_relays.rs       | 25 ++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

diff --git a/mullvad-relay-selector/src/relay_selector/parsed_relays.rs b/mullvad-relay-selector/src/relay_selector/parsed_relays.rs
index 2f2a3f89e35c..7b53b529ee88 100644
--- a/mullvad-relay-selector/src/relay_selector/parsed_relays.rs
+++ b/mullvad-relay-selector/src/relay_selector/parsed_relays.rs
@@ -1,4 +1,11 @@
-//! TODO(markus): Document this!
+//! This module provides functionality for managing and updating the local relay list,
+//! including support for loading these lists from disk & applying [overrides][`RelayOverride`].
+//!
+//! ## Overview
+//!
+//! The primary structure in this module, [`ParsedRelays`], holds information about the currently
+//! available relays, including any overrides that have been applied to the original list fetched
+//! from the Mullvad API or loaded from a local cache.
 
 use std::{
     collections::HashMap,
@@ -16,8 +23,11 @@ use mullvad_types::{
 use crate::{constants::UDP2TCP_PORTS, error::Error};
 
 pub(crate) struct ParsedRelays {
+    /// Tracks when the relay list was last updated.
     last_updated: SystemTime,
+    /// The current list of relays, after applying [overrides][`RelayOverride`].
     parsed_list: RelayList,
+    /// The original list of relays, as returned by the Mullvad relays API.
     original_list: RelayList,
     overrides: Vec<RelayOverride>,
 }
@@ -28,6 +38,8 @@ impl ParsedRelays {
         self.parsed_list.relays()
     }
 
+    /// Replace `self` with a new [`ParsedRelays`] based on [new_relays][`ParsedRelays`],
+    /// bumping `self.last_updated` to the current system time.
     pub fn update(&mut self, new_relays: RelayList) {
         *self = Self::from_relay_list(new_relays, SystemTime::now(), &self.overrides);
 
@@ -37,6 +49,9 @@ impl ParsedRelays {
         );
     }
 
+    /// Tracks when the relay list was last updated.
+    ///
+    /// The relay list can be updated by calling [`ParsedRelays::update`].
     pub const fn last_updated(&self) -> SystemTime {
         self.last_updated
     }
@@ -45,14 +60,18 @@ impl ParsedRelays {
         self.parsed_list.etag.clone()
     }
 
+    /// The original list of relays, as returned by the Mullvad relays API.
     pub const fn original_list(&self) -> &RelayList {
         &self.original_list
     }
 
+    /// The current list of relays, after applying [overrides][`RelayOverride`].
     pub const fn parsed_list(&self) -> &RelayList {
         &self.parsed_list
     }
 
+    /// Replace the previous set of [overrides][`RelayOverride`] with `new_overrides`.
+    /// This will update `self.parsed_list` as a side-effect.
     pub(crate) fn set_overrides(&mut self, new_overrides: &[RelayOverride]) {
         self.parsed_list = Self::parse_relay_list(&self.original_list, new_overrides);
         self.overrides = new_overrides.to_vec();
@@ -110,6 +129,8 @@ impl ParsedRelays {
         Ok((last_modified, file))
     }
 
+    /// Create a new [`ParsedRelays`] from [relay_list][`RelayList`] and [overrides][`RelayOverride`].
+    /// This will apply `overrides` to `relay_list` and store the result in `self.parsed_list`.
     pub(crate) fn from_relay_list(
         relay_list: RelayList,
         last_updated: SystemTime,
@@ -123,6 +144,8 @@ impl ParsedRelays {
         }
     }
 
+    /// Apply [overrides][`RelayOverride`] to [relay_list][`RelayList`], yielding an updated relay
+    /// list.
     fn parse_relay_list(relay_list: &RelayList, overrides: &[RelayOverride]) -> RelayList {
         let mut remaining_overrides = HashMap::new();
         for relay_override in overrides {