add more comments about DHT direct requests

include/libtorrent/alert_types.hpp

@@ -2382,6 +2382,8 @@ namespace libtorrent
 		int m_peers_idx;
 	};
 
+	// This is posted exactly once for every call to session_handle::dht_direct_request.
+	// If the request failed, response() will return a default constructed bdecode_node.
 	struct TORRENT_EXPORT dht_direct_response_alert: alert
 	{
 		dht_direct_response_alert(aux::stack_allocator& alloc, void* userdata

include/libtorrent/extensions.hpp

@@ -192,9 +192,12 @@ namespace libtorrent
 	struct peer_connection_handle;
 	struct torrent_handle;
 
+	// Functions of this type are called to handle incoming DHT requests
 	typedef boost::function<bool(udp::endpoint const& source
 		, bdecode_node const& request, entry& response)> dht_extension_handler_t;
 
+	// Map of query strings to handlers. Note that query strings are limited to 15 bytes.
+	// see max_dht_query_length
 	typedef std::vector<std::pair<std::string, dht_extension_handler_t> > dht_extensions_t;
 
 	// this is the base class for a session plugin. One primary feature

include/libtorrent/session_handle.hpp

@@ -431,6 +431,12 @@ namespace libtorrent
 		void dht_get_peers(sha1_hash const& info_hash);
 		void dht_announce(sha1_hash const& info_hash, int port = 0, int flags = 0);
 
+		// Send an arbitrary DHT request directly to the specified endpoint. This
+		// function is intended for use by plugins. Whan a response is received
+		// or the request times out, a dht_direct_response_alert will be posted
+		// with the response (if any) and the userdata pointer passed in here.
+		// Since this alert is a reponse to an explicit call, it will always be
+		// posted, regardless of the alert mask.
 		void dht_direct_request(boost::asio::ip::udp::endpoint ep, entry const& e, void* userdata);
 
 #ifndef TORRENT_NO_DEPRECATE