net: move Doxygen docs from netbase.cpp to netbase.h

2 files changed, 136 insertions, 129 deletions

diff --git a/src/netbase.cpp b/src/netbase.cpp
index 17b030eb70..ac2392ebed 100644
--- a/src/netbase.cpp
+++ b/src/netbase.cpp
@@ -166,21 +166,6 @@ static bool LookupIntern(const std::string& name, std::vector<CNetAddr>& vIP, un
     return (vIP.size() > 0);
 }
 
-/**
- * Resolve a host string to its corresponding network addresses.
- *
- * @param name    The string representing a host. Could be a name or a numerical
- *                IP address (IPv6 addresses in their bracketed form are
- *                allowed).
- * @param[out] vIP The resulting network addresses to which the specified host
- *                 string resolved.
- *
- * @returns Whether or not the specified host string successfully resolved to
- *          any resulting network addresses.
- *
- * @see Lookup(const std::string&, std::vector<CService>&, int, bool, unsigned int, DNSLookupFn)
- *      for additional parameter descriptions.
- */
 bool LookupHost(const std::string& name, std::vector<CNetAddr>& vIP, unsigned int nMaxSolutions, bool fAllowLookup, DNSLookupFn dns_lookup_function)
 {
     if (!ValidAsCString(name)) {
@@ -196,12 +181,6 @@ bool LookupHost(const std::string& name, std::vector<CNetAddr>& vIP, unsigned in
     return LookupIntern(strHost, vIP, nMaxSolutions, fAllowLookup, dns_lookup_function);
 }
 
- /**
- * Resolve a host string to its first corresponding network address.
- *
- * @see LookupHost(const std::string&, std::vector<CNetAddr>&, unsigned int, bool, DNSLookupFn)
- *      for additional parameter descriptions.
- */
 bool LookupHost(const std::string& name, CNetAddr& addr, bool fAllowLookup, DNSLookupFn dns_lookup_function)
 {
     if (!ValidAsCString(name)) {
@@ -215,26 +194,6 @@ bool LookupHost(const std::string& name, CNetAddr& addr, bool fAllowLookup, DNSL
     return true;
 }
 
-/**
- * Resolve a service string to its corresponding service.
- *
- * @param name    The string representing a service. Could be a name or a
- *                numerical IP address (IPv6 addresses should be in their
- *                disambiguated bracketed form), optionally followed by a port
- *                number. (e.g. example.com:8333 or
- *                [2001:db8:85a3:8d3:1319:8a2e:370:7348]:420)
- * @param[out] vAddr The resulting services to which the specified service string
- *                   resolved.
- * @param portDefault The default port for resulting services if not specified
- *                    by the service string.
- * @param fAllowLookup Whether or not hostname lookups are permitted. If yes,
- *                     external queries may be performed.
- * @param nMaxSolutions The maximum number of results we want, specifying 0
- *                      means "as many solutions as we get."
- *
- * @returns Whether or not the service string successfully resolved to any
- *          resulting services.
- */
 bool Lookup(const std::string& name, std::vector<CService>& vAddr, int portDefault, bool fAllowLookup, unsigned int nMaxSolutions, DNSLookupFn dns_lookup_function)
 {
     if (name.empty() || !ValidAsCString(name)) {
@@ -254,12 +213,6 @@ bool Lookup(const std::string& name, std::vector<CService>& vAddr, int portDefau
     return true;
 }
 
-/**
- * Resolve a service string to its first corresponding service.
- *
- * @see Lookup(const std::string&, std::vector<CService>&, int, bool, unsigned int, DNSLookupFn)
- *      for additional parameter descriptions.
- */
 bool Lookup(const std::string& name, CService& addr, int portDefault, bool fAllowLookup, DNSLookupFn dns_lookup_function)
 {
     if (!ValidAsCString(name)) {
@@ -273,15 +226,6 @@ bool Lookup(const std::string& name, CService& addr, int portDefault, bool fAllo
     return true;
 }
 
-/**
- * Resolve a service string with a numeric IP to its first corresponding
- * service.
- *
- * @returns The resulting CService if the resolution was successful, [::]:0 otherwise.
- *
- * @see Lookup(const std::string&, std::vector<CService>&, int, bool, unsigned int, DNSLookupFn)
- *      for additional parameter descriptions.
- */
 CService LookupNumeric(const std::string& name, int portDefault, DNSLookupFn dns_lookup_function)
 {
     if (!ValidAsCString(name)) {
@@ -419,24 +363,6 @@ static std::string Socks5ErrorString(uint8_t err)
     }
 }
 
-/**
- * Connect to a specified destination service through an already connected
- * SOCKS5 proxy.
- *
- * @param strDest The destination fully-qualified domain name.
- * @param port The destination port.
- * @param auth The credentials with which to authenticate with the specified
- *             SOCKS5 proxy.
- * @param sock The SOCKS5 proxy socket.
- *
- * @returns Whether or not the operation succeeded.
- *
- * @note The specified SOCKS5 proxy socket must already be connected to the
- *       SOCKS5 proxy.
- *
- * @see <a href="https://www.ietf.org/rfc/rfc1928.txt">RFC1928: SOCKS Protocol
- *      Version 5</a>
- */
 bool Socks5(const std::string& strDest, int port, const ProxyCredentials* auth, const Sock& sock)
 {
     IntrRecvError recvr;
@@ -611,18 +537,6 @@ static void LogConnectFailure(bool manual_connection, const char* fmt, const Arg
     }
 }
 
-/**
- * Try to connect to the specified service on the specified socket.
- *
- * @param addrConnect The service to which to connect.
- * @param hSocket The socket on which to connect.
- * @param nTimeout Wait this many milliseconds for the connection to be
- *                 established.
- * @param manual_connection Whether or not the connection was manually requested
- *                          (e.g. through the addnode RPC)
- *
- * @returns Whether or not a connection was successfully made.
- */
 bool ConnectSocketDirectly(const CService &addrConnect, const SOCKET& hSocket, int nTimeout, bool manual_connection)
 {
     // Create a sockaddr from the specified service.
@@ -721,22 +635,6 @@ bool GetProxy(enum Network net, proxyType &proxyInfoOut) {
     return true;
 }
 
-/**
- * Set the name proxy to use for all connections to nodes specified by a
- * hostname. After setting this proxy, connecting to a node specified by a
- * hostname won't result in a local lookup of said hostname, rather, connect to
- * the node by asking the name proxy for a proxy connection to the hostname,
- * effectively delegating the hostname lookup to the specified proxy.
- *
- * This delegation increases privacy for those who set the name proxy as they no
- * longer leak their external hostname queries to their DNS servers.
- *
- * @returns Whether or not the operation succeeded.
- *
- * @note SOCKS5's support for UDP-over-SOCKS5 has been considered, but no SOCK5
- *       server in common use (most notably Tor) actually implements UDP
- *       support, and a DNS resolver is beyond the scope of this project.
- */
 bool SetNameProxy(const proxyType &addrProxy) {
     if (!addrProxy.IsValid())
         return false;
@@ -767,21 +665,6 @@ bool IsProxy(const CNetAddr &addr) {
     return false;
 }
 
-/**
- * Connect to a specified destination service through a SOCKS5 proxy by first
- * connecting to the SOCKS5 proxy.
- *
- * @param proxy The SOCKS5 proxy.
- * @param strDest The destination service to which to connect.
- * @param port The destination port.
- * @param sock The socket on which to connect to the SOCKS5 proxy.
- * @param nTimeout Wait this many milliseconds for the connection to the SOCKS5
- *                 proxy to be established.
- * @param[out] outProxyConnectionFailed Whether or not the connection to the
- *                                      SOCKS5 proxy failed.
- *
- * @returns Whether or not the operation succeeded.
- */
 bool ConnectThroughProxy(const proxyType& proxy, const std::string& strDest, int port, const Sock& sock, int nTimeout, bool& outProxyConnectionFailed)
 {
     // first connect to proxy server
@@ -805,17 +688,6 @@ bool ConnectThroughProxy(const proxyType& proxy, const std::string& strDest, int
     return true;
 }
 
-/**
- * Parse and resolve a specified subnet string into the appropriate internal
- * representation.
- *
- * @param strSubnet A string representation of a subnet of the form `network
- *                address [ "/", ( CIDR-style suffix | netmask ) ]`(e.g.
- *                `2001:db8::/32`, `192.0.2.0/255.255.255.0`, or `8.8.8.8`).
- * @param ret The resulting internal representation of a subnet.
- *
- * @returns Whether the operation succeeded or not.
- */
 bool LookupSubNet(const std::string& strSubnet, CSubNet& ret, DNSLookupFn dns_lookup_function)
 {
     if (!ValidAsCString(strSubnet)) {
diff --git a/src/netbase.h b/src/netbase.h
index 227da1a63b..e13ca4dbc5 100644
--- a/src/netbase.h
+++ b/src/netbase.h
@@ -76,6 +76,22 @@ std::vector<std::string> GetNetworkNames(bool append_unroutable = false);
 bool SetProxy(enum Network net, const proxyType &addrProxy);
 bool GetProxy(enum Network net, proxyType &proxyInfoOut);
 bool IsProxy(const CNetAddr &addr);
+/**
+ * Set the name proxy to use for all connections to nodes specified by a
+ * hostname. After setting this proxy, connecting to a node specified by a
+ * hostname won't result in a local lookup of said hostname, rather, connect to
+ * the node by asking the name proxy for a proxy connection to the hostname,
+ * effectively delegating the hostname lookup to the specified proxy.
+ *
+ * This delegation increases privacy for those who set the name proxy as they no
+ * longer leak their external hostname queries to their DNS servers.
+ *
+ * @returns Whether or not the operation succeeded.
+ *
+ * @note SOCKS5's support for UDP-over-SOCKS5 has been considered, but no SOCK5
+ *       server in common use (most notably Tor) actually implements UDP
+ *       support, and a DNS resolver is beyond the scope of this project.
+ */
 bool SetNameProxy(const proxyType &addrProxy);
 bool HaveNameProxy();
 bool GetNameProxy(proxyType &nameProxyOut);
@@ -83,11 +99,83 @@ bool GetNameProxy(proxyType &nameProxyOut);
 using DNSLookupFn = std::function<std::vector<CNetAddr>(const std::string&, bool)>;
 extern DNSLookupFn g_dns_lookup;
 
+/**
+ * Resolve a host string to its corresponding network addresses.
+ *
+ * @param name    The string representing a host. Could be a name or a numerical
+ *                IP address (IPv6 addresses in their bracketed form are
+ *                allowed).
+ * @param[out] vIP The resulting network addresses to which the specified host
+ *                 string resolved.
+ *
+ * @returns Whether or not the specified host string successfully resolved to
+ *          any resulting network addresses.
+ *
+ * @see Lookup(const std::string&, std::vector<CService>&, int, bool, unsigned int, DNSLookupFn)
+ *      for additional parameter descriptions.
+ */
 bool LookupHost(const std::string& name, std::vector<CNetAddr>& vIP, unsigned int nMaxSolutions, bool fAllowLookup, DNSLookupFn dns_lookup_function = g_dns_lookup);
+
+/**
+ * Resolve a host string to its first corresponding network address.
+ *
+ * @see LookupHost(const std::string&, std::vector<CNetAddr>&, unsigned int, bool, DNSLookupFn)
+ *      for additional parameter descriptions.
+ */
 bool LookupHost(const std::string& name, CNetAddr& addr, bool fAllowLookup, DNSLookupFn dns_lookup_function = g_dns_lookup);
-bool Lookup(const std::string& name, CService& addr, int portDefault, bool fAllowLookup, DNSLookupFn dns_lookup_function = g_dns_lookup);
+
+/**
+ * Resolve a service string to its corresponding service.
+ *
+ * @param name    The string representing a service. Could be a name or a
+ *                numerical IP address (IPv6 addresses should be in their
+ *                disambiguated bracketed form), optionally followed by a port
+ *                number. (e.g. example.com:8333 or
+ *                [2001:db8:85a3:8d3:1319:8a2e:370:7348]:420)
+ * @param[out] vAddr The resulting services to which the specified service string
+ *                   resolved.
+ * @param portDefault The default port for resulting services if not specified
+ *                    by the service string.
+ * @param fAllowLookup Whether or not hostname lookups are permitted. If yes,
+ *                     external queries may be performed.
+ * @param nMaxSolutions The maximum number of results we want, specifying 0
+ *                      means "as many solutions as we get."
+ *
+ * @returns Whether or not the service string successfully resolved to any
+ *          resulting services.
+ */
 bool Lookup(const std::string& name, std::vector<CService>& vAddr, int portDefault, bool fAllowLookup, unsigned int nMaxSolutions, DNSLookupFn dns_lookup_function = g_dns_lookup);
+
+/**
+ * Resolve a service string to its first corresponding service.
+ *
+ * @see Lookup(const std::string&, std::vector<CService>&, int, bool, unsigned int, DNSLookupFn)
+ *      for additional parameter descriptions.
+ */
+bool Lookup(const std::string& name, CService& addr, int portDefault, bool fAllowLookup, DNSLookupFn dns_lookup_function = g_dns_lookup);
+
+/**
+ * Resolve a service string with a numeric IP to its first corresponding
+ * service.
+ *
+ * @returns The resulting CService if the resolution was successful, [::]:0 otherwise.
+ *
+ * @see Lookup(const std::string&, std::vector<CService>&, int, bool, unsigned int, DNSLookupFn)
+ *      for additional parameter descriptions.
+ */
 CService LookupNumeric(const std::string& name, int portDefault = 0, DNSLookupFn dns_lookup_function = g_dns_lookup);
+
+/**
+ * Parse and resolve a specified subnet string into the appropriate internal
+ * representation.
+ *
+ * @param strSubnet A string representation of a subnet of the form `network
+ *                address [ "/", ( CIDR-style suffix | netmask ) ]`(e.g.
+ *                `2001:db8::/32`, `192.0.2.0/255.255.255.0`, or `8.8.8.8`).
+ * @param ret The resulting internal representation of a subnet.
+ *
+ * @returns Whether the operation succeeded or not.
+ */
 bool LookupSubNet(const std::string& strSubnet, CSubNet& subnet, DNSLookupFn dns_lookup_function = g_dns_lookup);
 
 /**
@@ -102,14 +190,61 @@ std::unique_ptr<Sock> CreateSockTCP(const CService& address_family);
  */
 extern std::function<std::unique_ptr<Sock>(const CService&)> CreateSock;
 
+/**
+ * Try to connect to the specified service on the specified socket.
+ *
+ * @param addrConnect The service to which to connect.
+ * @param hSocket The socket on which to connect.
+ * @param nTimeout Wait this many milliseconds for the connection to be
+ *                 established.
+ * @param manual_connection Whether or not the connection was manually requested
+ *                          (e.g. through the addnode RPC)
+ *
+ * @returns Whether or not a connection was successfully made.
+ */
 bool ConnectSocketDirectly(const CService &addrConnect, const SOCKET& hSocketRet, int nTimeout, bool manual_connection);
+
+/**
+ * Connect to a specified destination service through a SOCKS5 proxy by first
+ * connecting to the SOCKS5 proxy.
+ *
+ * @param proxy The SOCKS5 proxy.
+ * @param strDest The destination service to which to connect.
+ * @param port The destination port.
+ * @param sock The socket on which to connect to the SOCKS5 proxy.
+ * @param nTimeout Wait this many milliseconds for the connection to the SOCKS5
+ *                 proxy to be established.
+ * @param[out] outProxyConnectionFailed Whether or not the connection to the
+ *                                      SOCKS5 proxy failed.
+ *
+ * @returns Whether or not the operation succeeded.
+ */
 bool ConnectThroughProxy(const proxyType& proxy, const std::string& strDest, int port, const Sock& sock, int nTimeout, bool& outProxyConnectionFailed);
+
 /** Disable or enable blocking-mode for a socket */
 bool SetSocketNonBlocking(const SOCKET& hSocket, bool fNonBlocking);
 /** Set the TCP_NODELAY flag on a socket */
 bool SetSocketNoDelay(const SOCKET& hSocket);
 void InterruptSocks5(bool interrupt);
 
+/**
+ * Connect to a specified destination service through an already connected
+ * SOCKS5 proxy.
+ *
+ * @param strDest The destination fully-qualified domain name.
+ * @param port The destination port.
+ * @param auth The credentials with which to authenticate with the specified
+ *             SOCKS5 proxy.
+ * @param sock The SOCKS5 proxy socket.
+ *
+ * @returns Whether or not the operation succeeded.
+ *
+ * @note The specified SOCKS5 proxy socket must already be connected to the
+ *       SOCKS5 proxy.
+ *
+ * @see <a href="https://www.ietf.org/rfc/rfc1928.txt">RFC1928: SOCKS Protocol
+ *      Version 5</a>
+ */
 bool Socks5(const std::string& strDest, int port, const ProxyCredentials* auth, const Sock& socket);
 
 #endif // BITCOIN_NETBASE_H