[doc] Update comments

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

1 files changed, 15 insertions, 2 deletions

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;