[doc] Update comments

Maintain comments on the external interfaces rather than on the internal
functions that implement them.

3 files changed, 16 insertions, 30 deletions

diff --git a/src/addrman.cpp b/src/addrman.cpp
index 40e087f5fb..3ccd3751bc 100644
--- a/src/addrman.cpp
+++ b/src/addrman.cpp
@@ -23,7 +23,7 @@
 static constexpr uint32_t ADDRMAN_TRIED_BUCKETS_PER_GROUP{8};
 /** Over how many buckets entries with new addresses originating from a single group are spread */
 static constexpr uint32_t ADDRMAN_NEW_BUCKETS_PER_SOURCE_GROUP{64};
-/** Maximum number of times an address can be added to the new table */
+/** Maximum number of times an address can occur in the new table */
 static constexpr int32_t ADDRMAN_NEW_BUCKETS_PER_ADDRESS{8};
 /** How old addresses can maximally be */
 static constexpr int64_t ADDRMAN_HORIZON_DAYS{30};
diff --git a/src/addrman.h b/src/addrman.h
index 688265d345..84c2bf2201 100644
--- a/src/addrman.h
+++ b/src/addrman.h
@@ -74,7 +74,7 @@ public:
     //! Add addresses to addrman's new table.
     bool Add(const std::vector<CAddress> &vAddr, const CNetAddr& source, int64_t nTimePenalty = 0);
 
-    //! Mark an entry as accessible.
+    //! Mark an entry as accessible, possibly moving it from "new" to "tried".
     void Good(const CService &addr, int64_t nTime = GetAdjustedTime());
 
     //! Mark an entry as connection attempted to.
@@ -107,12 +107,25 @@ public:
      * @param[in] max_addresses  Maximum number of addresses to return (0 = all).
      * @param[in] max_pct        Maximum percentage of addresses to return (0 = all).
      * @param[in] network        Select only addresses of this network (nullopt = all).
+     *
+     * @return                   A vector of randomly selected addresses from vRandom.
      */
     std::vector<CAddress> GetAddr(size_t max_addresses, size_t max_pct, std::optional<Network> network) const;
 
-    //! Outer function for Connected_()
+    /** We have successfully connected to this peer. Calling this function
+     *  updates the CAddress's nTime, which is used in our IsTerrible()
+     *  decisions and gossiped to peers. Callers should be careful that updating
+     *  this information doesn't leak topology information to network spies.
+     *
+     *  net_processing calls this function when it *disconnects* from a peer to
+     *  not leak information about currently connected peers.
+     *
+     * @param[in]   addr     The address of the peer we were connected to
+     * @param[in]   nTime    The time that we were last connected to this peer
+     */
     void Connected(const CService &addr, int64_t nTime = GetAdjustedTime());
 
+    //! Update an entry's service bits.
     void SetServices(const CService &addr, ServiceFlags nServices);
 
     const std::vector<bool>& GetAsmap() const;
diff --git a/src/addrman_impl.h b/src/addrman_impl.h
index 918034caf8..160efb2c0e 100644
--- a/src/addrman_impl.h
+++ b/src/addrman_impl.h
@@ -227,49 +227,22 @@ private:
     //! Move an entry from the "new" table(s) to the "tried" table
     void MakeTried(CAddrInfo& info, int nId) EXCLUSIVE_LOCKS_REQUIRED(cs);
 
-    //! Mark an entry "good", possibly moving it from "new" to "tried".
     void Good_(const CService &addr, bool test_before_evict, int64_t time) EXCLUSIVE_LOCKS_REQUIRED(cs);
 
-    //! Add an entry to the "new" table.
     bool Add_(const CAddress &addr, const CNetAddr& source, int64_t nTimePenalty) EXCLUSIVE_LOCKS_REQUIRED(cs);
 
-    //! Mark an entry as attempted to connect.
     void Attempt_(const CService &addr, bool fCountFailure, int64_t nTime) EXCLUSIVE_LOCKS_REQUIRED(cs);
 
-    //! Select an address to connect to, if newOnly is set to true, only the new table is selected from.
     std::pair<CAddress, int64_t> Select_(bool newOnly) const EXCLUSIVE_LOCKS_REQUIRED(cs);
 
-    /**
-     * Return all or many randomly selected addresses, optionally by network.
-     *
-     * @param[in] max_addresses  Maximum number of addresses to return (0 = all).
-     * @param[in] max_pct        Maximum percentage of addresses to return (0 = all).
-     * @param[in] network        Select only addresses of this network (nullopt = all).
-     *
-     * @returns                  A vector of randomly selected addresses from vRandom.
-     */
     std::vector<CAddress> GetAddr_(size_t max_addresses, size_t max_pct, std::optional<Network> network) const EXCLUSIVE_LOCKS_REQUIRED(cs);
 
-    /** We have successfully connected to this peer. Calling this function
-     *  updates the CAddress's nTime, which is used in our IsTerrible()
-     *  decisions and gossiped to peers. Callers should be careful that updating
-     *  this information doesn't leak topology information to network spies.
-     *
-     *  net_processing calls this function when it *disconnects* from a peer to
-     *  not leak information about currently connected peers.
-     *
-     * @param[in]   addr     The address of the peer we were connected to
-     * @param[in]   nTime    The time that we were last connected to this peer
-     */
     void Connected_(const CService& addr, int64_t nTime) EXCLUSIVE_LOCKS_REQUIRED(cs);
 
-    //! Update an entry's service bits.
     void SetServices_(const CService &addr, ServiceFlags nServices) EXCLUSIVE_LOCKS_REQUIRED(cs);
 
-    //! See if any to-be-evicted tried table entries have been tested and if so resolve the collisions.
     void ResolveCollisions_() EXCLUSIVE_LOCKS_REQUIRED(cs);
 
-    //! Return a random to-be-evicted tried table address.
     std::pair<CAddress, int64_t> SelectTriedCollision_() EXCLUSIVE_LOCKS_REQUIRED(cs);
 
     //! Consistency check, taking into account m_consistency_check_ratio. Will std::abort if an inconsistency is detected.