documentation and deprecation fixes (#1275)

documentation and deprecation fixes

examples/client_test.cpp

@@ -1322,9 +1322,6 @@ int main(int argc, char* argv[])
 	settings.set_int(settings_pack::choking_algorithm, settings_pack::rate_based_choker);
 
 	int refresh_delay = 500;
-#ifndef TORRENT_DISABLE_DHT
-	bool start_dht = true;
-#endif
 	bool rate_limit_locals = false;
 
 	std::deque<std::string> events;
@@ -1420,9 +1417,6 @@ int main(int argc, char* argv[])
 			case 't': poll_interval = atoi(arg); break;
 			case 'F': refresh_delay = atoi(arg); break;
 			case 'H':
-#ifndef TORRENT_DISABLE_DHT
-				start_dht = false;
-#endif
 				settings.set_bool(settings_pack::enable_dht, false);
 				--i;
 				break;
@@ -1601,18 +1595,6 @@ int main(int argc, char* argv[])
 	dht.privacy_lookups = true;
 	ses.set_dht_settings(dht);
 
-	if (start_dht)
-	{
-		settings.set_bool(settings_pack::use_dht_as_fallback, false);
-
-		ses.add_dht_router(std::make_pair(
-			std::string("router.bittorrent.com"), 6881));
-		ses.add_dht_router(std::make_pair(
-			std::string("router.utorrent.com"), 6881));
-		ses.add_dht_router(std::make_pair(
-			std::string("router.bitcomet.com"), 6881));
-	}
-
 	std::vector<char> in;
 	if (load_file(".ses_state", in, ec) == 0)
 	{

include/libtorrent/session_handle.hpp

@@ -367,6 +367,10 @@ namespace libtorrent
 		// ``add_dht_node`` takes a host name and port pair. That endpoint will be
 		// pinged, and if a valid DHT reply is received, the node will be added to
 		// the routing table.
+		void add_dht_node(std::pair<std::string, int> const& node);
+
+#ifndef TORRENT_NO_DEPRECATE
+		// deprecated, use settings_pack::dht_bootstrap_nodes instead
 		//
 		// ``add_dht_router`` adds the given endpoint to a list of DHT router
 		// nodes. If a search is ever made while the routing table is empty,
@@ -377,8 +381,9 @@ namespace libtorrent
 		//
 		// An example routing node that you could typically add is
 		// ``router.bittorrent.com``.
-		void add_dht_node(std::pair<std::string, int> const& node);
+		TORRENT_DEPRECATED
 		void add_dht_router(std::pair<std::string, int> const& node);
+#endif
 
 		// query the DHT for an immutable item at the ``target`` hash.
 		// the result is posted as a dht_immutable_item_alert.
@@ -600,28 +605,7 @@ namespace libtorrent
 		// settings_pack::listen_interfaces to try another interface and port to
 		// bind to.
 		//
-		// ``listen_port()`` returns the port we ended up listening on. If the
-		// port specified in settings_pack::listen_interfaces failed, libtorrent
-		// will try to bind to the next port, and so on. If it fails
-		// settings_pack::max_retry_port_bind times, it will bind to port 0
-		// (meaning the OS picks the port). The only way to know which port it
-		// ended up binding to is to ask for it by calling ``listen_port()``.
-		//
-		// If all ports in the specified range fails to be opened for listening,
-		// libtorrent will try to use port 0 (which tells the operating system to
-		// pick a port that's free). If that still fails you may see a
-		// listen_failed_alert with port 0 even if you didn't ask to listen on
-		// it.
-		//
-		// It is possible to prevent libtorrent from falling back to binding to
-		// port 0 by clearing the ``listen_system_port_fallback`` settings.
-		//
-		// The interface parameter can also be a hostname that will resolve to
-		// the device you want to listen on. If you don't specify an interface,
-		// libtorrent may attempt to listen on multiple interfaces (typically
-		// 0.0.0.0 and ::). This means that if your IPv6 interface doesn't work,
-		// you may still see a listen_failed_alert, even though the IPv4 port
-		// succeeded.
+		// ``listen_port()`` returns the port we ended up listening on.
 		unsigned short listen_port() const;
 		unsigned short ssl_listen_port() const;
 		bool is_listening() const;

include/libtorrent/settings_pack.hpp

@@ -173,11 +173,18 @@ namespace libtorrent
 			// IPs and multiple ports. Binding to port 0 will make the
 			// operating system pick the port. The default is "0.0.0.0:6881", which
 			// binds to all interfaces on port 6881.
-			//
+			// 
+			// If binding fails because the port is busy, the port number will be
+			// incremented by one, ``settings_pack::max_retry_port_bind`` times.
+			// 
+			// if all retry attempts fail, the socket will be bound to port 0,
+			// meaning the operating system will pick a port. This behavior can be
+			// disabled by disabling ``settings_pack::listen_system_port_fallback``.
+			// 
 			// if binding fails, the listen_failed_alert is posted, potentially
 			// more than once. Once/if binding the listen socket(s) succeed,
 			// listen_succeeded_alert is posted.
-			//
+			// 
 			// Each port will attempt to open both a UDP and a TCP listen socket,
 			// to allow accepting uTP connections as well as TCP. If using the DHT,
 			// this will also make the DHT use the same UDP ports.

src/session_handle.cpp

@@ -370,6 +370,7 @@ namespace libtorrent
 #endif
 	}
 
+#ifndef TORRENT_NO_DEPRECATE
 	void session_handle::add_dht_router(std::pair<std::string, int> const& node)
 	{
 #ifndef TORRENT_DISABLE_DHT
@@ -378,6 +379,7 @@ namespace libtorrent
 		TORRENT_UNUSED(node);
 #endif
 	}
+#endif // TORRENT_NO_DEPRECATE
 
 	void session_handle::dht_get_item(sha1_hash const& target)
 	{