moved more documentation over from manual to headers

docs/manual.rst

@@ -93,248 +93,6 @@ For documentation on these types, please refer to the `asio documentation`_.
 
 .. _`asio documentation`: http://asio.sourceforge.net/asio-0.3.8/doc/asio/reference.html
 
-peer_info
-=========
-
-It contains the following fields::
-
-	struct peer_info
-	{
-		enum
-		{
-			interesting = 0x1,
-			choked = 0x2,
-			remote_interested = 0x4,
-			remote_choked = 0x8,
-			supports_extensions = 0x10,
-			local_connection = 0x20,
-			handshake = 0x40,
-			connecting = 0x80,
-			queued = 0x100,
-			on_parole = 0x200,
-			seed = 0x400,
-			optimistic_unchoke = 0x800,
-			snubbed = 0x1000,
-			upload_only = 0x2000,
-			endgame_mode = 0x4000,
-			holepunched = 0x8000,
-			rc4_encrypted = 0x100000,
-			plaintext_encrypted = 0x200000
-		};
-
-		unsigned int flags;
-
-		enum peer_source_flags
-		{
-			tracker = 0x1,
-			dht = 0x2,
-			pex = 0x4,
-			lsd = 0x8
-		};
-
-		int source;
-
-		// bitmask representing socket state
-		enum bw_state { bw_idle = 0, bw_limit = 1, bw_network = 2, bw_disk = 4 };
-
-		char read_state;
-		char write_state;
-
-		asio::ip::tcp::endpoint ip;
-		int up_speed;
-		int down_speed;
-		int payload_up_speed;
-		int payload_down_speed;
-		size_type total_download;
-		size_type total_upload;
-		peer_id pid;
-		bitfield pieces;
-		int upload_limit;
-		int download_limit;
-
-		time_duration last_request;
-		time_duration last_active;
-		int request_timeout;
-
-		int send_buffer_size;
-		int used_send_buffer;
-
-		int receive_buffer_size;
-		int used_receive_buffer;
-
-		int num_hashfails;
-
-		char country[2];
-
-		std::string inet_as_name;
-		int inet_as;
-
-		size_type load_balancing;
-
-		int requests_in_buffer;
-		int download_queue_length;
-		int upload_queue_length;
-
-		int failcount;
-
-		int downloading_piece_index;
-		int downloading_block_index;
-		int downloading_progress;
-		int downloading_total;
-
-		std::string client;
-
-		enum
-		{
-			standard_bittorrent = 0,
-			web_seed = 1
-		};
-		int connection_type;
-
-		int remote_dl_rate;
-
-		int pending_disk_bytes;
-
-		int send_quota;
-		int receive_quota;
-
-		int rtt;
-
-		int num_pieces;
-
-		int download_rate_peak;
-		int upload_rate_peak;
-
-		float progress;
-		int progress_ppm;
-
-		tcp::endpoint local_endpoint;
-	};
-
-
-feed_handle
-===========
-
-The ``feed_handle`` refers to a specific RSS feed which is watched by the session.
-The ``feed_item`` struct is defined in ``<libtorrent/rss.hpp>``. It has the following
-functions::
-
-	struct feed_handle
-	{
-		feed_handle();
-		void update_feed();
-		feed_status get_feed_status() const;
-		void set_settings(feed_settings const& s);
-		feed_settings settings() const;
-	};
-
-update_feed()
--------------
-
-	::
-
-		void update_feed();
-
-Forces an update/refresh of the feed. Regular updates of the feed is managed
-by libtorrent, be careful to not call this too frequently since it may
-overload the RSS server.
-
-get_feed_status()
------------------
-
-	::
-
-		feed_status get_feed_status() const;
-
-Queries the RSS feed for information, including all the items in the feed.
-The ``feed_status`` object has the following fields::
-
-	struct feed_status
-	{
-		std::string url;
-		std::string title;
-		std::string description;
-		time_t last_update;
-		int next_update;
-		bool updating;
-		std::vector<feed_item> items;
-		error_code error;
-		int ttl;
-	};
-
-``url`` is the URL of the feed.
-
-``title`` is the name of the feed (as specified by the feed itself). This
-may be empty if we have not recevied a response from the RSS server yet,
-or if the feed does not specify a title.
-
-``description`` is the feed description (as specified by the feed itself).
-This may be empty if we have not received a response from the RSS server
-yet, or if the feed does not specify a description.
-
-``last_update`` is the posix time of the last successful response from the feed.
-
-``next_update`` is the number of seconds, from now, when the feed will be
-updated again.
-
-``updating`` is true if the feed is currently being updated (i.e. waiting for
-DNS resolution, connecting to the server or waiting for the response to the
-HTTP request, or receiving the response).
-
-``items`` is a vector of all items that we have received from the feed. See
-feed_item_ for more information.
-
-``error`` is set to the appropriate error code if the feed encountered an
-error.
-
-``ttl`` is the current refresh time (in minutes). It's either the configured
-default ttl, or the ttl specified by the feed.
-
-
-set_settings() settings()
--------------------------
-
-	::
-
-		void set_settings(feed_settings const& s);
-		feed_settings settings() const;
-
-Sets and gets settings for this feed. For more information on the
-available settings, see `add_feed()`_.
-
-feed_item
-=========
-
-The ``feed_item`` struct is defined in ``<libtorrent/rss.hpp>``.
-
-	::
-
-		struct feed_item
-		{
-			feed_item();
-			std::string url;
-			std::string uuid;
-			std::string title;
-			std::string description;
-			std::string comment;
-			std::string category;
-			size_type size;
-			torrent_handle handle;
-			sha1_hash info_hash;
-		};
-
-``size`` is the total size of the content the torrent refers to, or -1
-if no size was specified by the feed.
-
-``handle`` is the handle to the torrent, if the session is already downloading
-this torrent.
-
-``info_hash`` is the info-hash of the torrent, or cleared (i.e. all zeroes) if
-the feed does not specify the info-hash.
-
-All the strings are self explanatory and may be empty if the feed does not specify
-those fields.
-
 session customization
 =====================
 
@@ -346,35 +104,6 @@ You have control over proxy and authorization settings and also the user-agent
 that will be sent to the tracker. The user-agent will also be used to identify the
 client with other peers.
 
-presets
--------
-
-The default values of the session settings are set for a regular bittorrent client running
-on a desktop system. There are functions that can set the session settings to pre set
-settings for other environments. These can be used for the basis, and should be tweaked to
-fit your needs better.
-
-::
-
-	session_settings min_memory_usage();
-	session_settings high_performance_seed();
-
-``min_memory_usage`` returns settings that will use the minimal amount of RAM, at the
-potential expense of upload and download performance. It adjusts the socket buffer sizes,
-disables the disk cache, lowers the send buffer watermarks so that each connection only has
-at most one block in use at any one time. It lowers the outstanding blocks send to the disk
-I/O thread so that connections only have one block waiting to be flushed to disk at any given
-time. It lowers the max number of peers in the peer list for torrents. It performs multiple
-smaller reads when it hashes pieces, instead of reading it all into memory before hashing.
-
-This configuration is inteded to be the starting point for embedded devices. It will
-significantly reduce memory usage.
-
-``high_performance_seed`` returns settings optimized for a seed box, serving many peers
-and that doesn't do any downloading. It has a 128 MB disk cache and has a limit of 400 files
-in its file pool. It support fast upload rates by allowing large send buffers.
-
-
 session_settings
 ----------------
 
@@ -1539,112 +1268,6 @@ disabled by default. Enabling it makes the cache perform better at high throughp
 It also makes the cache less likely and slower at returning memory back to the system
 once allocated.
 
-big_number
-==========
-
-Both the ``peer_id`` and ``sha1_hash`` types are typedefs of the class
-``big_number``. It represents 20 bytes of data. Its synopsis follows::
-
-	class big_number
-	{
-	public:
-		bool operator==(const big_number& n) const;
-		bool operator!=(const big_number& n) const;
-		bool operator<(const big_number& n) const;
-
-		const unsigned char* begin() const;
-		const unsigned char* end() const;
-
-		unsigned char* begin();
-		unsigned char* end();
-	};
-
-The iterators gives you access to individual bytes.
-
-UPnP and NAT-PMP
-================
-
-The ``upnp`` and ``natpmp`` classes contains the state for all UPnP and NAT-PMP mappings,
-by default 1 or two mappings are made by libtorrent, one for the listen port and one
-for the DHT port (UDP).
-
-::
-
-	class upnp
-	{
-	public:
-
-		enum protocol_type { none = 0, udp = 1, tcp = 2 };
-		int add_mapping(protocol_type p, int external_port, int local_port);
-		void delete_mapping(int mapping_index);
-	
-		void discover_device();
-		void close();
-	
-		std::string router_model();
-	};
-
-	class natpmp
-	{
-	public:
-	
-		enum protocol_type { none = 0, udp = 1, tcp = 2 };
-		int add_mapping(protocol_type p, int external_port, int local_port);
-		void delete_mapping(int mapping_index);
-	
-		void close();
-		void rebind(address const& listen_interface);
-	};
-
-``discover_device()``, ``close()`` and ``rebind()`` are for internal uses and should
-not be called directly by clients.
-
-add_mapping()
--------------
-
-	::
-
-		int add_mapping(protocol_type p, int external_port, int local_port);
-
-Attempts to add a port mapping for the specified protocol. Valid protocols are
-``upnp::tcp`` and ``upnp::udp`` for the UPnP class and ``natpmp::tcp`` and
-``natpmp::udp`` for the NAT-PMP class.
-
-``external_port`` is the port on the external address that will be mapped. This
-is a hint, you are not guaranteed that this port will be available, and it may
-end up being something else. In the portmap_alert_ notification, the actual
-external port is reported.
-
-``local_port`` is the port in the local machine that the mapping should forward
-to.
-
-The return value is an index that identifies this port mapping. This is used
-to refer to mappings that fails or succeeds in the portmap_error_alert_ and
-portmap_alert_ respectively. If The mapping fails immediately, the return value
-is -1, which means failure. There will not be any error alert notification for
-mappings that fail with a -1 return value.
-
-delete_mapping()
-----------------
-
-	::
-
-		void delete_mapping(int mapping_index);
-
-This function removes a port mapping. ``mapping_index`` is the index that refers
-to the mapping you want to remove, which was returned from `add_mapping()`_.
-
-router_model()
---------------
-
-	::
-
-		std::string router_model();
-
-This is only available for UPnP routers. If the model is advertized by
-the router, it can be queried through this function.
-
-
 torrent_added_alert
 -------------------
 
@@ -2954,55 +2577,6 @@ of the info-hash changing.
 
 ``old_ih`` and ``new_ih`` are the previous and new info-hash for the torrent, respectively.
 
-alert dispatcher
-================
-
-The ``handle_alert`` class is defined in ``<libtorrent/alert.hpp>``.
-
-Examples usage::
-
-	struct my_handler
-	{
-		void operator()(portmap_error_alert const& a) const
-		{
-			std::cout << "Portmapper: " << a.msg << std::endl;
-		}
-
-		void operator()(tracker_warning_alert const& a) const
-		{
-			std::cout << "Tracker warning: " << a.msg << std::endl;
-		}
-
-		void operator()(torrent_finished_alert const& a) const
-		{
-			// write fast resume data
-			// ...
-
-			std::cout << a.handle.torrent_file()->name() << "completed"
-				<< std::endl;
-		}
-	};
-
-::
-
-	std::auto_ptr<alert> a;
-	a = ses.pop_alert();
-	my_handler h;
-	while (a.get())
-	{
-		handle_alert<portmap_error_alert
-			, tracker_warning_alert
-			, torrent_finished_alert
-		>::handle_alert(h, a);
-		a = ses.pop_alert();
-	}
-
-In this example 3 alert types are used. You can use any number of template
-parameters to select between more types. If the number of types are more than
-15, you can define ``TORRENT_MAX_ALERT_TYPES`` to a greater number before
-including ``<libtorrent/alert.hpp>``.
-
-
 exceptions
 ==========
 
@@ -3810,8 +3384,9 @@ The benefits of this mode are:
 compact allocation
 ------------------
 
-Note that support for compact allocation is deprecated in libttorrent, and will
+.. note::
-be removed in future versions.
+	Note that support for compact allocation is deprecated in libttorrent, and will
+	be removed in future versions.
 
 The compact allocation will only allocate as much storage as it needs to keep the
 pieces downloaded so far. This means that pieces will be moved around to be placed

include/libtorrent/alert.hpp

@@ -58,78 +58,15 @@ POSSIBILITY OF SUCH DAMAGE.
 // 
 // By default, only errors are reported. set_alert_mask() can be
 // used to specify which kinds of events should be reported. The alert mask
-// is a bitmask with the following bits:
+// is comprised by bits from the category_t enum.
-// 
-// +--------------------------------+---------------------------------------------------------------------+
-// | ``error_notification``         | Enables alerts that report an error. This includes:                 |
-// |                                |                                                                     |
-// |                                | * tracker errors                                                    |
-// |                                | * tracker warnings                                                  |
-// |                                | * file errors                                                       |
-// |                                | * resume data failures                                              |
-// |                                | * web seed errors                                                   |
-// |                                | * .torrent files errors                                             |
-// |                                | * listen socket errors                                              |
-// |                                | * port mapping errors                                               |
-// +--------------------------------+---------------------------------------------------------------------+
-// | ``peer_notification``          | Enables alerts when peers send invalid requests, get banned or      |
-// |                                | snubbed.                                                            |
-// +--------------------------------+---------------------------------------------------------------------+
-// | ``port_mapping_notification``  | Enables alerts for port mapping events. For NAT-PMP and UPnP.       |
-// +--------------------------------+---------------------------------------------------------------------+
-// | ``storage_notification``       | Enables alerts for events related to the storage. File errors and   |
-// |                                | synchronization events for moving the storage, renaming files etc.  |
-// +--------------------------------+---------------------------------------------------------------------+
-// | ``tracker_notification``       | Enables all tracker events. Includes announcing to trackers,        |
-// |                                | receiving responses, warnings and errors.                           |
-// +--------------------------------+---------------------------------------------------------------------+
-// | ``debug_notification``         | Low level alerts for when peers are connected and disconnected.     |
-// +--------------------------------+---------------------------------------------------------------------+
-// | ``status_notification``        | Enables alerts for when a torrent or the session changes state.     |
-// +--------------------------------+---------------------------------------------------------------------+
-// | ``progress_notification``      | Alerts for when blocks are requested and completed. Also when       |
-// |                                | pieces are completed.                                               |
-// +--------------------------------+---------------------------------------------------------------------+
-// | ``ip_block_notification``      | Alerts when a peer is blocked by the ip blocker or port blocker.    |
-// +--------------------------------+---------------------------------------------------------------------+
-// | ``performance_warning``        | Alerts when some limit is reached that might limit the download     |
-// |                                | or upload rate.                                                     |
-// +--------------------------------+---------------------------------------------------------------------+
-// | ``stats_notification``         | If you enable these alerts, you will receive a stats_alert          |
-// |                                | approximately once every second, for every active torrent.          |
-// |                                | These alerts contain all statistics counters for the interval since |
-// |                                | the lasts stats alert.                                              |
-// +--------------------------------+---------------------------------------------------------------------+
-// | ``dht_notification``           | Alerts on events in the DHT node. For incoming searches or          |
-// |                                | bootstrapping being done etc.                                       |
-// +--------------------------------+---------------------------------------------------------------------+
-// | ``rss_notification``           | Alerts on RSS related events, like feeds being updated, feed error  |
-// |                                | conditions and successful RSS feed updates. Enabling this categoty  |
-// |                                | will make you receive rss_alert alerts.                             |
-// +--------------------------------+---------------------------------------------------------------------+
-// | ``all_categories``             | The full bitmask, representing all available categories.            |
-// +--------------------------------+---------------------------------------------------------------------+
 // 
 // Every alert belongs to one or more category. There is a small cost involved in posting alerts. Only
 // alerts that belong to an enabled category are posted. Setting the alert bitmask to 0 will disable
-// all alerts
+// all alerts (except those that are non-discardable).
 // 
-// There's another alert base class that some alerts derive from, all the
+// There are other alert base classes that some alerts derive from, all the
-// alerts that are generated for a specific torrent are derived from::
+// alerts that are generated for a specific torrent are derived from torrent_alert,
-// 
+// and tracker events derive from tracker_alert.
-//	struct torrent_alert: alert
-//	{
-//		// ...
-//		torrent_handle handle;
-//	};
-// 
-// There's also a base class for all alerts referring to tracker events::
-// 
-//	struct tracker_alert: torrent_alert
-//	{
-//		// ...
-//		std::string url;
-//	};
 //
 
 #ifdef _MSC_VER
@@ -161,20 +98,67 @@ namespace libtorrent {
 
 		enum category_t
 		{
+			// Enables alerts that report an error. This includes:
+			// 
+			// * tracker errors
+			// * tracker warnings
+			// * file errors
+			// * resume data failures
+			// * web seed errors
+			// * .torrent files errors
+			// * listen socket errors
+			// * port mapping errors
 			error_notification = 0x1,
+
+			// Enables alerts when peers send invalid requests, get banned or
+			// snubbed.
 			peer_notification = 0x2,
+
+			// Enables alerts for port mapping events. For NAT-PMP and UPnP.
 			port_mapping_notification = 0x4,
+
+			// Enables alerts for events related to the storage. File errors and  
+			// synchronization events for moving the storage, renaming files etc. 
 			storage_notification = 0x8,
+
+			// Enables all tracker events. Includes announcing to trackers,
+			// receiving responses, warnings and errors.
 			tracker_notification = 0x10,
+
+			// Low level alerts for when peers are connected and disconnected.
 			debug_notification = 0x20,
+
+			// Enables alerts for when a torrent or the session changes state.
 			status_notification = 0x40,
+
+			// Alerts for when blocks are requested and completed. Also when
+			// pieces are completed.
 			progress_notification = 0x80,
+
+			// Alerts when a peer is blocked by the ip blocker or port blocker.   
 			ip_block_notification = 0x100,
+
+			// Alerts when some limit is reached that might limit the download    
+			// or upload rate.
 			performance_warning = 0x200,
+
+			// Alerts on events in the DHT node. For incoming searches or
+			// bootstrapping being done etc.
 			dht_notification = 0x400,
+
+			// If you enable these alerts, you will receive a stats_alert
+			// approximately once every second, for every active torrent.
+			// These alerts contain all statistics counters for the interval since
+			// the lasts stats alert.
 			stats_notification = 0x800,
+
+			// Alerts on RSS related events, like feeds being updated, feed error 
+			// conditions and successful RSS feed updates. Enabling this categoty 
+			// will make you receive rss_alert alerts.
 			rss_notification = 0x1000,
 
+			// The full bitmask, representing all available categories.
+			//
 			// since the enum is signed, make sure this isn't
 			// interpreted as -1. For instance, boost.python
 			// does that and fails when assigning it to an
@@ -251,6 +235,7 @@ namespace libtorrent {
 		unhandled_alert() {}
 	};
 
+#ifndef TORRENT_NO_DEPRECATE
 #ifndef BOOST_NO_TYPEID
 
 	namespace detail {
@@ -302,12 +287,10 @@ namespace libtorrent {
 	};
 
 #endif // BOOST_NO_TYPEID
+#endif // TORRENT_NO_DEPRECATE
 
 // When you get an alert, you can use ``alert_cast<>`` to attempt to cast the pointer to a
 // more specific alert type, in order to query it for more information.
-//
-// You can also use a `alert dispatcher`_ mechanism that's available in libtorrent.
-
 template <class T>
 T* alert_cast(alert* a)
 {

include/libtorrent/rss.hpp

@@ -45,18 +45,33 @@ namespace libtorrent
 	namespace aux
 	{ struct session_impl; }
 
+	// represents one item from an RSS feed. Specifically
+	// a feed of torrents.
+	//
 	struct TORRENT_EXPORT feed_item
 	{
 		feed_item();
 		~feed_item();
+
+		// these are self explanatory and may be empty if the feed does not specify
+		// those fields.
 		std::string url;
 		std::string uuid;
 		std::string title;
 		std::string description;
 		std::string comment;
 		std::string category;
+
+		// the total size of the content the torrent refers to, or -1
+		// if no size was specified by the feed.
 		size_type size;
+
+		// the handle to the torrent, if the session is already downloading
+		// this torrent.
 		torrent_handle handle;
+
+		// the info-hash of the torrent, or cleared (i.e. all zeroes) if
+		// the feed does not specify the info-hash.
 		sha1_hash info_hash;
 	};
 
@@ -114,28 +129,69 @@ namespace libtorrent
 		add_torrent_params add_args;
 	};
 
+	// holds information about the status of an RSS feed. Retrieved by
+	// calling get_feed_status() on feed_handle.
 	struct TORRENT_EXPORT feed_status
 	{
 		feed_status(): last_update(0), next_update(0)
 			, updating(false), ttl(0) {}
+
+		// the URL of the feed.
 		std::string url;
+
+		// the name of the feed (as specified by the feed itself). This
+		// may be empty if we have not recevied a response from the RSS server yet,
+		// or if the feed does not specify a title.
 		std::string title;
+
+		// the feed description (as specified by the feed itself).
+		// This may be empty if we have not received a response from the RSS server
+		// yet, or if the feed does not specify a description.
 		std::string description;
+
+		// the posix time of the last successful response from the feed.
 		time_t last_update;
+
+		// the number of seconds, from now, when the feed will be
+		// updated again.
 		int next_update;
+
+		// true if the feed is currently being updated (i.e. waiting for
+		// DNS resolution, connecting to the server or waiting for the response to the
+		// HTTP request, or receiving the response).
 		bool updating;
+
+		// a vector of all items that we have received from the feed. See
+		// feed_item for more information.
 		std::vector<feed_item> items;
+
+		// set to the appropriate error code if the feed encountered an
+		// error. See error_code for more info.
 		error_code error;
+
+		// the current refresh time (in minutes). It's either the configured
+		// default ttl, or the ttl specified by the feed.
 		int ttl;
 	};
 
 	struct feed;
 
+	// The ``feed_handle`` refers to a specific RSS feed that is watched by the session.
 	struct TORRENT_EXPORT feed_handle
 	{
 		feed_handle() {}
+
+		// Forces an update/refresh of the feed. Regular updates of the feed is managed
+		// by libtorrent, be careful to not call this too frequently since it may
+		// overload the RSS server.
 		void update_feed();
+
+		// Queries the RSS feed for information, including all the items in the feed.
+		// see feed_status.
 		feed_status get_feed_status() const;
+
+		// Sets and gets settings for this feed. For more information on the
+		// available settings, see add_feed().
 		void set_settings(feed_settings const& s);
 		feed_settings settings() const;
 	private:

include/libtorrent/session.hpp

@@ -82,6 +82,25 @@ namespace libtorrent
 	class connection_queue;
 	class alert;
 
+	// The default values of the session settings are set for a regular bittorrent client running
+	// on a desktop system. There are functions that can set the session settings to pre set
+	// settings for other environments. These can be used for the basis, and should be tweaked to
+	// fit your needs better.
+	// 
+	// ``min_memory_usage`` returns settings that will use the minimal amount of RAM, at the
+	// potential expense of upload and download performance. It adjusts the socket buffer sizes,
+	// disables the disk cache, lowers the send buffer watermarks so that each connection only has
+	// at most one block in use at any one time. It lowers the outstanding blocks send to the disk
+	// I/O thread so that connections only have one block waiting to be flushed to disk at any given
+	// time. It lowers the max number of peers in the peer list for torrents. It performs multiple
+	// smaller reads when it hashes pieces, instead of reading it all into memory before hashing.
+	// 
+	// This configuration is inteded to be the starting point for embedded devices. It will
+	// significantly reduce memory usage.
+	// 
+	// ``high_performance_seed`` returns settings optimized for a seed box, serving many peers
+	// and that doesn't do any downloading. It has a 128 MB disk cache and has a limit of 400 files
+	// in its file pool. It support fast upload rates by allowing large send buffers.
 	TORRENT_EXPORT session_settings min_memory_usage();
 	TORRENT_EXPORT session_settings high_performance_seed();
 
@@ -498,8 +517,6 @@ namespace libtorrent
 		// ``as_for_ip`` returns the AS number for the IP address specified. If the IP is not
 		// in the database or the ASN database is not loaded, 0 is returned.
 		// 
-		// The ``wchar_t`` overloads are for wide character paths.
-		// 
 		// .. _`MaxMind ASN database`: http://www.maxmind.com/app/asnum
 		// .. _`MaxMind GeoIP database`: http://www.maxmind.com/app/geolitecountry
 #ifndef TORRENT_DISABLE_GEO_IP

include/libtorrent/upnp.hpp

@@ -118,8 +118,8 @@ namespace libtorrent
 typedef boost::function<void(int, address, int, error_code const&)> portmap_callback_t;
 typedef boost::function<void(char const*)> log_callback_t;
 
-// TODO: 2 make this a shared_ptr instead
 class TORRENT_EXTRA_EXPORT upnp : public intrusive_ptr_base<upnp>
+// TODO: 2 make this a shared_ptr instead
 {
 public:
 	upnp(io_service& ios, connection_queue& cc
@@ -131,13 +131,37 @@ public:
 	void* drain_state();
 
 	enum protocol_type { none = 0, udp = 1, tcp = 2 };
+
+	// Attempts to add a port mapping for the specified protocol. Valid protocols are
+	// ``upnp::tcp`` and ``upnp::udp`` for the UPnP class and ``natpmp::tcp`` and
+	// ``natpmp::udp`` for the NAT-PMP class.
+	// 
+	// ``external_port`` is the port on the external address that will be mapped. This
+	// is a hint, you are not guaranteed that this port will be available, and it may
+	// end up being something else. In the portmap_alert_ notification, the actual
+	// external port is reported.
+	// 
+	// ``local_port`` is the port in the local machine that the mapping should forward
+	// to.
+	// 
+	// The return value is an index that identifies this port mapping. This is used
+	// to refer to mappings that fails or succeeds in the portmap_error_alert_ and
+	// portmap_alert_ respectively. If The mapping fails immediately, the return value
+	// is -1, which means failure. There will not be any error alert notification for
+	// mappings that fail with a -1 return value.
 	int add_mapping(protocol_type p, int external_port, int local_port);
+
+	// This function removes a port mapping. ``mapping_index`` is the index that refers
+	// to the mapping you want to remove, which was returned from add_mapping().
 	void delete_mapping(int mapping_index);
+
 	bool get_mapping(int mapping_index, int& local_port, int& external_port, int& protocol) const;
 
 	void discover_device();
 	void close();
 
+	// This is only available for UPnP routers. If the model is advertized by
+	// the router, it can be queried through this function.
 	std::string router_model()
 	{
 		mutex::scoped_lock l(m_mutex);