diff --git a/src/netaddress.h b/src/netaddress.h
--- a/src/netaddress.h
+++ b/src/netaddress.h
@@ -48,10 +48,6 @@
     void SetRaw(Network network, const uint8_t *data);
 
 public:
-    /**
-     * Transform an arbitrary string into a non-routable ipv6 address.
-     * Useful for mapping resolved addresses back to their source.
-     */
     bool SetInternal(const std::string &name);
 
     // for Tor addresses
@@ -87,9 +83,10 @@
     bool IsRFC7343() const;
     // IPv6 autoconfig (FE80::/64)
     bool IsRFC4862() const;
-    // IPv6 well-known prefix (64:FF9B::/96)
+    // IPv6 well-known prefix for IPv4-embedded address (64:FF9B::/96)
     bool IsRFC6052() const;
-    // IPv6 IPv4-translated address (::FFFF:0:0:0/96)
+    // IPv6 IPv4-translated address (::FFFF:0:0:0/96) (actually defined in
+    // RFC2765)
     bool IsRFC6145() const;
     bool IsTor() const;
     bool IsLocal() const;
diff --git a/src/netaddress.cpp b/src/netaddress.cpp
--- a/src/netaddress.cpp
+++ b/src/netaddress.cpp
@@ -18,6 +18,11 @@
 // 0xFD + sha256("bitcoin")[0:5]
 static const uint8_t g_internal_prefix[] = {0xFD, 0x6B, 0x88, 0xC0, 0x87, 0x24};
 
+/**
+ * Construct an unspecified IPv6 network address (::/128).
+ *
+ * @note This address is considered invalid by CNetAddr::IsValid()
+ */
 CNetAddr::CNetAddr() {
     memset(ip, 0, sizeof(ip));
 }
@@ -40,6 +45,20 @@
     }
 }
 
+/**
+ * Try to make this a dummy address that maps the specified name into IPv6 like
+ * so: (0xFD + %sha256("bitcoin")[0:5]) + %sha256(name)[0:10]. Such dummy
+ * addresses have a prefix of fd6b:88c0:8724::/48 and are guaranteed to not be
+ * publicly routable as it falls under RFC4193's fc00::/7 subnet allocated to
+ * unique-local addresses.
+ *
+ * CAddrMan uses these fake addresses to keep track of which DNS seeds were
+ * used.
+ *
+ * @returns Whether or not the operation was successful.
+ *
+ * @see CNetAddr::IsInternal(), CNetAddr::IsRFC4193()
+ */
 bool CNetAddr::SetInternal(const std::string &name) {
     if (name.empty()) {
         return false;
@@ -52,6 +71,16 @@
     return true;
 }
 
+/**
+ * Try to make this a dummy address that maps the specified onion address into
+ * IPv6 using OnionCat's range and encoding. Such dummy addresses have a prefix
+ * of fd87:d87e:eb43::/48 and are guaranteed to not be publicly routable as they
+ * fall under RFC4193's fc00::/7 subnet allocated to unique-local addresses.
+ *
+ * @returns Whether or not the operation was successful.
+ *
+ * @see CNetAddr::IsTor(), CNetAddr::IsRFC4193()
+ */
 bool CNetAddr::SetSpecial(const std::string &strName) {
     if (strName.size() > 6 &&
         strName.substr(strName.size() - 6, 6) == ".onion") {
@@ -173,6 +202,12 @@
             (GetByte(12) & 0xF0) == 0x20);
 }
 
+/**
+ * @returns Whether or not this is a dummy address that maps an onion address
+ *          into IPv6.
+ *
+ * @see CNetAddr::SetSpecial(const std::string &)
+ */
 bool CNetAddr::IsTor() const {
     return (memcmp(ip, pchOnionCat, sizeof(pchOnionCat)) == 0);
 }
@@ -193,6 +228,16 @@
     return false;
 }
 
+/**
+ * @returns Whether or not this network address is a valid address that @a could
+ *          be used to refer to an actual host.
+ *
+ * @note A valid address may or may not be publicly routable on the global
+ *       internet. As in, the set of valid addresses is a superset of the set of
+ *       publicly routable addresses.
+ *
+ * @see CNetAddr::IsRoutable()
+ */
 bool CNetAddr::IsValid() const {
     // Cleanup 3-byte shifted addresses caused by garbage in size field of addr
     // messages from versions before 0.2.9 checksum.
@@ -236,6 +281,15 @@
     return true;
 }
 
+/**
+ * @returns Whether or not this network address is publicly routable on the
+ *          global internet.
+ *
+ * @note A routable address is always valid. As in, the set of routable
+ * addresses is a subset of the set of valid addresses.
+ *
+ * @see CNetAddr::IsValid()
+ */
 bool CNetAddr::IsRoutable() const {
     return IsValid() &&
            !(IsRFC1918() || IsRFC2544() || IsRFC3927() || IsRFC4862() ||
@@ -243,6 +297,11 @@
              IsRFC4843() || IsRFC7343() || IsLocal() || IsInternal());
 }
 
+/**
+ * @returns Whether or not this is a dummy address that maps a name into IPv6.
+ *
+ * @see CNetAddr::SetInternal(const std::string &)
+ */
 bool CNetAddr::IsInternal() const {
     return memcmp(ip, g_internal_prefix, sizeof(g_internal_prefix)) == 0;
 }
@@ -311,6 +370,16 @@
     return (memcmp(a.ip, b.ip, 16) < 0);
 }
 
+/**
+ * Try to get our IPv4 address.
+ *
+ * @param[out] pipv4Addr The in_addr struct to which to copy.
+ *
+ * @returns Whether or not the operation was successful, in particular, whether
+ *          or not our address was an IPv4 address.
+ *
+ * @see CNetAddr::IsIPv4()
+ */
 bool CNetAddr::GetInAddr(struct in_addr *pipv4Addr) const {
     if (!IsIPv4()) {
         return false;
@@ -319,6 +388,16 @@
     return true;
 }
 
+/**
+ * Try to get our IPv6 address.
+ *
+ * @param[out] pipv6Addr The in6_addr struct to which to copy.
+ *
+ * @returns Whether or not the operation was successful, in particular, whether
+ *          or not our address was an IPv6 address.
+ *
+ * @see CNetAddr::IsIPv6()
+ */
 bool CNetAddr::GetIn6Addr(struct in6_addr *pipv6Addr) const {
     if (!IsIPv6()) {
         return false;
@@ -327,8 +406,16 @@
     return true;
 }
 
-// get canonical identifier of an address' group no two connections will be
-// attempted to addresses with the same group
+/**
+ * Get the canonical identifier of our network group
+ *
+ * The groups are assigned in a way where it should be costly for an attacker to
+ * obtain addresses with many different group identifiers, even if it is cheap
+ * to obtain addresses with the same identifier.
+ *
+ * @note No two connections will be attempted to addresses with the same network
+ *       group.
+ */
 std::vector<uint8_t> CNetAddr::GetGroup() const {
     std::vector<uint8_t> vchRet;
     int nClass = NET_IPV6;
@@ -380,11 +467,14 @@
     }
 
     vchRet.push_back(nClass);
+
+    // push our ip onto vchRet byte by byte...
     while (nBits >= 8) {
         vchRet.push_back(GetByte(15 - nStartByte));
         nStartByte++;
         nBits -= 8;
     }
+    // ...for the last byte, push nBits and for the rest of the byte push 1's
     if (nBits > 0) {
         vchRet.push_back(GetByte(15 - nStartByte) | ((1 << (8 - nBits)) - 1));
     }
@@ -545,6 +635,18 @@
             a.port < b.port);
 }
 
+/**
+ * Obtain the IPv4/6 socket address this represents.
+ *
+ * @param[out] paddr The obtained socket address.
+ * @param[in,out] addrlen The size, in bytes, of the address structure pointed
+ *                        to by paddr. The value that's pointed to by this
+ *                        parameter might change after calling this function if
+ *                        the size of the corresponding address structure
+ *                        changed.
+ *
+ * @returns Whether or not the operation was successful.
+ */
 bool CService::GetSockAddr(struct sockaddr *paddr, socklen_t *addrlen) const {
     if (IsIPv4()) {
         if (*addrlen < (socklen_t)sizeof(struct sockaddr_in)) {
@@ -580,11 +682,16 @@
     return false;
 }
 
+/**
+ * @returns An identifier unique to this service's address and port number.
+ */
 std::vector<uint8_t> CService::GetKey() const {
     std::vector<uint8_t> vKey;
     vKey.resize(18);
     memcpy(vKey.data(), ip, 16);
+    // most significant byte of our port
     vKey[16] = port / 0x100;
+    // least significant byte of our port
     vKey[17] = port & 0x0FF;
     return vKey;
 }
@@ -662,6 +769,10 @@
     network = addr;
 }
 
+/**
+ * @returns True if this subnet is valid, the specified address is valid, and
+ *          the specified address belongs in this subnet.
+ */
 bool CSubNet::Match(const CNetAddr &addr) const {
     if (!valid || !addr.IsValid()) {
         return false;
@@ -674,6 +785,10 @@
     return true;
 }
 
+/**
+ * @returns The number of 1-bits in the prefix of the specified subnet mask. If
+ *          the specified subnet mask is not a valid one, -1.
+ */
 static inline int NetmaskBits(uint8_t x) {
     switch (x) {
         case 0x00: