doc: upgrade some NOTE comments to docstrings

src/net/hosts.rs

@@ -935,7 +935,7 @@ impl Hosts {
     /// process fails, or when a channel stops. Prevents hosts from getting trapped in the
     /// HostState logical machinery.
     ///
-    /// NOTE: Misuse of this call is dangerous since it frees up the peer to be used by
+    /// Misuse of this call is dangerous since it frees up the peer to be used by
     /// the refinery or outbound connect loop, and may result in invalid states. It should
     /// only be called when it is completely safe to do so.
     pub async fn unregister(&self, addr: &Url) {

src/net/session/outbound_session.rs

@@ -195,20 +195,21 @@ impl Slot {
     /// Address selection algorithm that works as follows: up to
     /// anchor_count, select from the anchorlist. Up to white_count,
     /// select from the whitelist. For all other slots, select from
-    /// the greylist.
+    /// the greylist (this is SlotPreference::First).
     ///
     /// If we didn't find an address with this selection logic, downgrade
-    /// SlotPreference. Up to anchor_count, select from the whitelist,
-    /// up until white_count, select from the greylist.
+    /// SlotPreference to Second. Up to anchor_count, select from the
+    /// whitelist, up until white_count, select from the greylist.
     ///
-    /// If we still didn't find an address, select from the greylist. In
-    /// all other cases, return an empty vector. This will trigger
-    /// fetch_addrs() to return None and initiate peer discovery.
-    /* NOTE: Selecting from the greylist for some % of the slots is
-    necessary and healthy since we require the network retains some
-    unreliable connections. A network that purely favors uptime over
-    unreliable connections may be vulnerable to sybil by attackers with
-    good uptime.*/
+    /// If we still didn't find an address, downgrade SlotPreference to Last
+    /// and select from the greylist. In all other cases, return an empty
+    /// vector. This will trigger fetch_addrs() to return None and initiate
+    /// peer discovery.
+    ///
+    /// Selecting from the greylist for some % of the slots is necessary
+    /// and healthy since we require the network retains some unreliable
+    /// connections. A network that purely favors uptime over unreliable
+    /// connections may be vulnerable to sybil by attackers with good uptime.
     async fn fetch_addrs_with_preference(&self, preference: SlotPreference) -> Vec<(Url, u64)> {
         let slot = self.slot;
         let settings = self.p2p().settings();
@@ -459,10 +460,10 @@ impl Slot {
 }
 
 /// Defines a common interface for multiple peer discovery processes.
-/* NOTE: Currently only one Peer Discovery implementation exists. Making
-Peer Discovery generic enables us to support network swarming, since
-the peer discovery process will differ depending on whether it occurs
-on the overlay network or a subnet.*/
+/// Currently only one Peer Discovery implementation exists. Making
+/// Peer Discovery generic enables us to support network swarming, since
+/// the peer discovery process will differ depending on whether it occurs
+/// on the overlay network or a subnet.
 #[async_trait]
 pub trait PeerDiscoveryBase {
     async fn start(self: Arc<Self>);