diff --git a/docs/gen_reference_doc.py b/docs/gen_reference_doc.py
index 128f3a272..345453308 100644
--- a/docs/gen_reference_doc.py
+++ b/docs/gen_reference_doc.py
@@ -305,13 +305,12 @@ def parse_class(lno, lines, filename):
 						print 'WARNING: member function "%s" is not documented: \x1b[34m%s:%d\x1b[0m' \
 							% (name + '::' + first_item(current_fun['names']), filename, lno)
 					funs.append(current_fun)
-			context = ''
-			blanks = 0
+				context = ''
+				blanks = 0
 			continue
 
 		if looks_like_variable(l):
 			if not is_visible(context):
-				context = ''
 				continue
 			n = l.split(' ')[-1].split(':')[0].split(';')[0]
 			if context == '' and blanks == 0 and len(fields):
@@ -327,14 +326,17 @@ def parse_class(lno, lines, filename):
 			continue
 
 		if l.startswith('enum '):
-			enum, lno = parse_enum(lno - 1, lines, filename)
-			if enum != None and is_visible(context):
-				enum['desc'] = context
-				if context == '' and not suppress_warning(filename, enum['name']):
-					print 'WARNING: enum "%s" is not documented: \x1b[34m%s:%d\x1b[0m' \
-						% (name + '::' + enum['name'], filename, lno)
-				enums.append(enum)
-			context = ''
+			if not is_visible(context):
+				consume_block(lno - 1, lines)
+			else:
+				enum, lno = parse_enum(lno - 1, lines, filename)
+				if enum != None:
+					enum['desc'] = context
+					if context == '' and not suppress_warning(filename, enum['name']):
+						print 'WARNING: enum "%s" is not documented: \x1b[34m%s:%d\x1b[0m' \
+							% (name + '::' + enum['name'], filename, lno)
+					enums.append(enum)
+				context = ''
 			continue
 
 		context = ''
@@ -441,6 +443,13 @@ def consume_comment(lno, lines):
 
 	return lno
 
+def trim_define(l):
+	return l.replace('#ifndef', '').replace('#ifdef', '') \
+		.replace('#if', '').replace('defined', '') \
+		.replace('TORRENT_USE_IPV6', '').replace('TORRENT_NO_DEPRECATE', '') \
+		.replace('||', '').replace('&&', '').replace('(', '').replace(')','') \
+		.replace('!', '').replace('\\', '').strip()
+
 def consume_ifdef(lno, lines, warn_on_ifdefs = False):
 	l = lines[lno].strip()
 	lno += 1
@@ -451,17 +460,24 @@ def consume_ifdef(lno, lines, warn_on_ifdefs = False):
 	if verbose: print 'prep  %s' % l
 
 	if warn_on_ifdefs and ('TORRENT_DEBUG' in l or 'TORRENT_DISABLE_FULL_STATS' in l):
-		print '\x1b[31mWARNING: possible ABI breakage in public struct!\x1b[34m %s:%d\x1b[0m' % \
-			(filename, lno)
+		while l.endswith('\\'):
+			lno += 1
+			l += lines[lno].strip()
+			if verbose: print 'prep  %s' % lines[lno].trim()
+		define = trim_define(l)
+		print '\x1b[31mWARNING: possible ABI breakage in public struct! "%s" \x1b[34m %s:%d\x1b[0m' % \
+			(define, filename, lno)
+		# we've already warned once, no need to do it twice
+		warn_on_ifdefs = False
 
 	if warn_on_ifdefs and '#if' in l:
-		define = l.replace('#ifndef', '').replace('#ifdef', '') \
-			.replace('#if', '').replace('defined', '') \
-			.replace('TORRENT_USE_IPV6', '').replace('TORRENT_NO_DEPRECATE', '') \
-			.replace('||', '').replace('&&', '').replace('(', '').replace(')','') \
-			.replace('!', '').strip()
+		while l.endswith('\\'):
+			lno += 1
+			l += lines[lno].strip()
+			if verbose: print 'prep  %s' % lines[lno].trim()
+		define = trim_define(l)
 		if define != '':
-			print '\x1b[31msensitive define in public struct: "%s"\x1b[34m %s:%d\x1b[0m' % (define, filename, lno)
+			print '\x1b[33msensitive define in public struct: "%s"\x1b[34m %s:%d\x1b[0m' % (define, filename, lno)
 
 	if l == '#ifndef TORRENT_NO_DEPRECATE' or \
 		l == '#ifdef TORRENT_DEBUG' or \
@@ -543,6 +559,9 @@ for filename in files:
 			if verbose: print 'xx    %s' % l
 			continue
 		if 'TORRENT_DEPRECATED' in l:
+			if ('class ' in l or 'struct ' in l) and not ';' in l:
+				lno = consume_block(lno - 1, lines)
+				context = ''
 			blanks += 1
 			if verbose: print 'xx    %s' % l
 			continue
@@ -573,8 +592,8 @@ for filename in files:
 							print 'WARNING: function "%s" is not documented: \x1b[34m%s:%d\x1b[0m' \
 								% (first_item(current_fun['names']), filename, lno)
 						functions.append(current_fun)
+					context = ''
 					blanks = 0
-				context = ''
 				continue
 
 		if ('class ' in l or 'struct ' in l) and not ';' in l:
@@ -584,13 +603,16 @@ for filename in files:
 			continue
 
 		if l.startswith('enum '):
-			current_enum, lno = parse_enum(lno - 1, lines, filename)
-			if current_enum != None and is_visible(context):
-				current_enum['desc'] = context
-				if context == '':
-					print 'WARNING: enum "%s" is not documented: \x1b[34m%s:%d\x1b[0m' \
-						% (current_enum['name'], filename, lno)
-				enums.append(current_enum)
+			if not is_visible(context):
+				consume_block(lno - 1, lines)
+			else:
+				current_enum, lno = parse_enum(lno - 1, lines, filename)
+				if current_enum != None and is_visible(context):
+					current_enum['desc'] = context
+					if context == '':
+						print 'WARNING: enum "%s" is not documented: \x1b[34m%s:%d\x1b[0m' \
+							% (current_enum['name'], filename, lno)
+					enums.append(current_enum)
 			context = ''
 			blanks += 1
 			continue
diff --git a/include/libtorrent/add_torrent_params.hpp b/include/libtorrent/add_torrent_params.hpp
index 7a33bc92b..3cdc4833a 100644
--- a/include/libtorrent/add_torrent_params.hpp
+++ b/include/libtorrent/add_torrent_params.hpp
@@ -318,6 +318,9 @@ namespace libtorrent
 		// flags controlling aspects of this torrent and how it's added. See flags_t for details.
 		boost::uint64_t flags;
 
+		// set this to the info hash of the torrent to add in case the info-hash
+		// is the only known property of the torrent. i.e. you don't have a
+		// .torrent file nor a magnet link.
 		sha1_hash info_hash;
 
 		// ``max_uploads``, ``max_connections``, ``upload_limit``, ``download_limit`` correspond
diff --git a/include/libtorrent/error_code.hpp b/include/libtorrent/error_code.hpp
index 463f8beda..0b5dadc3c 100644
--- a/include/libtorrent/error_code.hpp
+++ b/include/libtorrent/error_code.hpp
@@ -544,6 +544,7 @@ namespace libtorrent
 #endif // BOOST_VERSION < 103600
 #endif // BOOST_VERSION < 103500
 
+	// internal
 	inline boost::system::error_category const& generic_category()
 	{ return get_posix_category(); }
 
diff --git a/include/libtorrent/extensions.hpp b/include/libtorrent/extensions.hpp
index 4e3d2c3a1..e5d03f109 100644
--- a/include/libtorrent/extensions.hpp
+++ b/include/libtorrent/extensions.hpp
@@ -82,7 +82,7 @@ POSSIBILITY OF SUCH DAMAGE.
 // ================
 // 
 // The plugin interface consists of three base classes that the plugin may
-// implement. These are called ``plugin``, ``torrent_plugin`` and ``peer_plugin``.
+// implement. These are called plugin, torrent_plugin and peer_plugin.
 // They are found in the ``<libtorrent/extensions.hpp>`` header.
 // 
 // These plugins are instantiated for each session, torrent and possibly each peer,
@@ -248,7 +248,7 @@ namespace libtorrent
 		// function).
 		// 
 		// If you need an extension to the peer connection (which most plugins do) you
-		// are supposed to return an instance of your ``peer_plugin`` class. Which in
+		// are supposed to return an instance of your peer_plugin class. Which in
 		// turn will have its hook functions called on event specific to that peer.
 		// 
 		// The ``peer_connection`` will be valid as long as the ``shared_ptr`` is being
@@ -315,6 +315,12 @@ namespace libtorrent
 			int /*src*/, int /*flags*/) {}
 	};
 
+	// peer plugins are associated with a specific peer. A peer could be
+	// both a regular bittorrent peer (``bt_peer_connection``) or one of the
+	// web seed connections (``web_peer_connection`` or ``http_seed_connection``).
+	// In order to only attach to certain peers, make your
+	// torrent_plugin::new_connection only return a plugin for certain peer
+	// connection types
 	struct TORRENT_EXPORT peer_plugin
 	{
 		// hidden
diff --git a/include/libtorrent/extensions/lt_trackers.hpp b/include/libtorrent/extensions/lt_trackers.hpp
index bc63cee83..e4d6f9295 100644
--- a/include/libtorrent/extensions/lt_trackers.hpp
+++ b/include/libtorrent/extensions/lt_trackers.hpp
@@ -48,6 +48,10 @@ namespace libtorrent
 {
 	struct torrent_plugin;
 	class torrent;
+
+	// constructor function for the trackers exchange extension. This can
+	// either be passed in the add_torrent_params::extensions field, or
+	// via torrent_handle::add_extension().
 	boost::shared_ptr<torrent_plugin> TORRENT_EXPORT create_lt_trackers_plugin(torrent*, void*);
 }
 
diff --git a/include/libtorrent/extensions/metadata_transfer.hpp b/include/libtorrent/extensions/metadata_transfer.hpp
index c42136d70..1af0d9ab2 100644
--- a/include/libtorrent/extensions/metadata_transfer.hpp
+++ b/include/libtorrent/extensions/metadata_transfer.hpp
@@ -48,7 +48,17 @@ namespace libtorrent
 {
 	struct torrent_plugin;
 	class torrent;
-	TORRENT_EXPORT boost::shared_ptr<torrent_plugin> create_metadata_plugin(torrent*, void*);
+
+#ifndef TORRENT_NO_DEPRECATE
+	// constructor function for the metadata transfer extension. This
+	// extension has been superceded by the ut_metadata extension and
+	// is deprecated. It can be either be passed in the
+	// add_torrent_params::extensions field, or
+	// via torrent_handle::add_extension().
+	TORRENT_DEPRECATED_PREFIX
+	TORRENT_EXPORT boost::shared_ptr<torrent_plugin>
+	create_metadata_plugin(torrent*, void*) TORRENT_DEPRECATED;
+#endif
 }
 
 #endif // TORRENT_METADATA_TRANSFER_HPP_INCLUDED
diff --git a/include/libtorrent/extensions/smart_ban.hpp b/include/libtorrent/extensions/smart_ban.hpp
index 5d7d30c82..27f321258 100644
--- a/include/libtorrent/extensions/smart_ban.hpp
+++ b/include/libtorrent/extensions/smart_ban.hpp
@@ -48,6 +48,13 @@ namespace libtorrent
 {
 	struct torrent_plugin;
 	class torrent;
+
+	// constructor function for the smart ban extension. The extension keeps
+	// track of the data peers have sent us for failing pieces and once the
+	// piece completes and passes the hash check bans the peers that turned
+	// out to have sent corrupt data.
+	// This function can either be passed in the add_torrent_params::extensions
+	// field, or via torrent_handle::add_extension().
 	TORRENT_EXPORT boost::shared_ptr<torrent_plugin> create_smart_ban_plugin(torrent*, void*);
 }
 
diff --git a/include/libtorrent/extensions/ut_metadata.hpp b/include/libtorrent/extensions/ut_metadata.hpp
index 91437b17c..e0b0b0750 100644
--- a/include/libtorrent/extensions/ut_metadata.hpp
+++ b/include/libtorrent/extensions/ut_metadata.hpp
@@ -48,6 +48,16 @@ namespace libtorrent
 {
 	struct torrent_plugin;
 	class torrent;
+
+	// constructor function for the ut_metadata extension. The ut_metadata
+	// extension allows peers to request the .torrent file (or more
+	// specifically the 'info'-dictionary of the .torrent file) from each
+	// other. This is the main building block in making magnet links work.
+	// This extension is enabled by default unless explicitly disabled in
+	// the session constructor.
+	// 
+	// This can either be passed in the add_torrent_params::extensions field, or
+	// via torrent_handle::add_extension().
 	TORRENT_EXPORT boost::shared_ptr<torrent_plugin> create_ut_metadata_plugin(torrent*, void*);
 }
 
diff --git a/include/libtorrent/extensions/ut_pex.hpp b/include/libtorrent/extensions/ut_pex.hpp
index ebf6aa834..256a29094 100644
--- a/include/libtorrent/extensions/ut_pex.hpp
+++ b/include/libtorrent/extensions/ut_pex.hpp
@@ -48,6 +48,15 @@ namespace libtorrent
 {
 	struct torrent_plugin;
 	class torrent;
+
+	// constructor function for the ut_pex extension. The ut_pex
+	// extension allows peers to gossip about their connections, allowing
+	// the swarm stay well connected and peers aware of more peers in the
+	// swarm. This extension is enabled by default unless explicitly disabled in
+	// the session constructor.
+	// 
+	// This can either be passed in the add_torrent_params::extensions field, or
+	// via torrent_handle::add_extension().
 	TORRENT_EXPORT boost::shared_ptr<torrent_plugin> create_ut_pex_plugin(torrent*, void*);
 }
 
diff --git a/include/libtorrent/file_storage.hpp b/include/libtorrent/file_storage.hpp
index 1f7ac81cc..8c2f2b176 100644
--- a/include/libtorrent/file_storage.hpp
+++ b/include/libtorrent/file_storage.hpp
@@ -161,6 +161,7 @@ namespace libtorrent
 			name_is_owned = (1<<12)-1,
 			not_a_symlink = (1<<15)-1
 		};
+
 		// the offset of this file inside the torrent
 		boost::uint64_t offset:48;
 
diff --git a/include/libtorrent/ip_filter.hpp b/include/libtorrent/ip_filter.hpp
index 18b15dfd3..16b9d972c 100644
--- a/include/libtorrent/ip_filter.hpp
+++ b/include/libtorrent/ip_filter.hpp
@@ -269,8 +269,11 @@ namespace detail
 // A default constructed ip_filter does not filter any address.
 struct TORRENT_EXPORT ip_filter
 {
+	// the flags defined for an IP range
 	enum access_flags
 	{
+		// indicates that IPs in this range should not be connected
+		// to nor accepted as incoming connections
 		blocked = 1
 	};
 
@@ -321,16 +324,30 @@ private:
 #endif
 };
 
+// the port filter maps non-overlapping port ranges to flags. This
+// is primarily used to indicate whether a range of ports should
+// be connected to or not. The default is to have the full port
+// range (0-65535) set to flag 0.
 class TORRENT_EXPORT port_filter
 {
 public:
 
+	// the defined flags for a port range
 	enum access_flags
 	{
+		// this flag indicates that destination ports in the
+		// range should not be connected to
 		blocked = 1
 	};
 
+	// set the flags for the specified port range (``first``, ``last``) to
+	// ``flags`` overwriting any existing rule for those ports. The range
+	// is inclusive, i.e. the port ``last`` also has the flag set on it.
 	void add_rule(boost::uint16_t first, boost::uint16_t last, int flags);
+
+	// test the specified port (``port``) for whether it is blocked
+	// or not. The returned value is the flags set for this port.
+	// see acces_flags.
 	int access(boost::uint16_t port) const;
 
 private:
diff --git a/include/libtorrent/peer_info.hpp b/include/libtorrent/peer_info.hpp
index a36a37051..ebf013fc5 100644
--- a/include/libtorrent/peer_info.hpp
+++ b/include/libtorrent/peer_info.hpp
@@ -42,6 +42,8 @@ POSSIBILITY OF SUCH DAMAGE.
 
 namespace libtorrent
 {
+	// holds information and statistics about one peer
+	// that libtorrent is connected to
 	struct TORRENT_EXPORT peer_info
 	{
 		enum peer_flags_t
@@ -59,76 +61,85 @@ namespace libtorrent
 			remote_choked = 0x8,
 
 			// means that this peer supports the
-			// `extension protocol`__.          
+			// `extension protocol`__.
 			// 
 			// __ extension_protocol.html
 			supports_extensions = 0x10,
 
-			// The connection was initiated by us, the peer has a   
+			// The connection was initiated by us, the peer has a
 			// listen port open, and that port is the same as in the
-			// address of this peer. If this flag is not set, this  
+			// address of this peer. If this flag is not set, this
 			// peer connection was opened by this peer connecting to
-			// us.                                                  
+			// us.
 			local_connection = 0x20,
 
-			// The connection is opened, and waiting for the        
-			// handshake. Until the handshake is done, the peer     
-			// cannot be identified.                                
+			// The connection is opened, and waiting for the
+			// handshake. Until the handshake is done, the peer
+			// cannot be identified.
 			handshake = 0x40,
 
-			// The connection is in a half-open state (i.e. it is   
-			// being connected).                                    
+			// The connection is in a half-open state (i.e. it is
+			// being connected).
 			connecting = 0x80,
 
-			// The connection is currently queued for a connection  
-			// attempt. This may happen if there is a limit set on  
-			// the number of half-open TCP connections.             
+			// The connection is currently queued for a connection
+			// attempt. This may happen if there is a limit set on
+			// the number of half-open TCP connections.
 			queued = 0x100,
 
-			// The peer has participated in a piece that failed the 
+			// The peer has participated in a piece that failed the
 			// hash check, and is now "on parole", which means we're
-			// only requesting whole pieces from this peer until    
-			// it either fails that piece or proves that it doesn't 
-			// send bad data.                                       
+			// only requesting whole pieces from this peer until
+			// it either fails that piece or proves that it doesn't
+			// send bad data.
 			on_parole = 0x200,
 
-			// This peer is a seed (it has all the pieces).         
+			// This peer is a seed (it has all the pieces).
 			seed = 0x400,
 
 			// This peer is subject to an optimistic unchoke. It has
-			// been unchoked for a while to see if it might unchoke 
-			// us in return an earn an upload/unchoke slot. If it   
+			// been unchoked for a while to see if it might unchoke
+			// us in return an earn an upload/unchoke slot. If it
 			// doesn't within some period of time, it will be choked
-			// and another peer will be optimistically unchoked.    
+			// and another peer will be optimistically unchoked.
 			optimistic_unchoke = 0x800,
 
-			// This peer has recently failed to send a block within 
-			// the request timeout from when the request was sent.  
+			// This peer has recently failed to send a block within
+			// the request timeout from when the request was sent.
 			// We're currently picking one block at a time from this
-			// peer.                                                
+			// peer.
 			snubbed = 0x1000,
 
-			// This peer has either explicitly (with an extension)  
-			// or implicitly (by becoming a seed) told us that it   
-			// will not downloading anything more, regardless of    
-			// which pieces we have.                                
+			// This peer has either explicitly (with an extension)
+			// or implicitly (by becoming a seed) told us that it
+			// will not downloading anything more, regardless of
+			// which pieces we have.
 			upload_only = 0x2000,
 
-			// This means the last time this peer picket a piece,   
-			// it could not pick as many as it wanted because there 
-			// were not enough free ones. i.e. all pieces this peer 
-			// has were already requested from other peers.         
+			// This means the last time this peer picket a piece,
+			// it could not pick as many as it wanted because there
+			// were not enough free ones. i.e. all pieces this peer
+			// has were already requested from other peers.
 			endgame_mode = 0x4000,
 
-			// This flag is set if the peer was in holepunch mode   
-			// when the connection succeeded. This typically only   
-			// happens if both peers are behind a NAT and the peers 
-			// connect via the NAT holepunch mechanism.             
+			// This flag is set if the peer was in holepunch mode
+			// when the connection succeeded. This typically only
+			// happens if both peers are behind a NAT and the peers
+			// connect via the NAT holepunch mechanism.
 			holepunched = 0x8000,
 
+			// indicates that this socket is runnin on top of the
+			// I2P transport.
 			i2p_socket = 0x10000,
+
+			// indicates that this socket is a uTP socket
 			utp_socket = 0x20000,
+
+			// this connection is obfuscated with RC4
 			rc4_encrypted = 0x100000,
+			
+			// the handshake of this connection was obfuscated
+			// with a diffie-hellman exchange
 			plaintext_encrypted = 0x200000
 		};
 
@@ -136,6 +147,9 @@ namespace libtorrent
 		// any combination of the peer_flags_t enum.
 		unsigned int flags;
 
+		// the flags indicating which sources a peer can
+		// have come from. A peer may have been seen from
+		// multiple sources
 		enum peer_source_flags
 		{
 			// The peer was received from the tracker.
diff --git a/include/libtorrent/peer_request.hpp b/include/libtorrent/peer_request.hpp
index 5ac535957..57e82ce36 100644
--- a/include/libtorrent/peer_request.hpp
+++ b/include/libtorrent/peer_request.hpp
@@ -35,6 +35,9 @@ POSSIBILITY OF SUCH DAMAGE.
 
 namespace libtorrent
 {
+
+	// represents a byte range within a piece. Internally this is
+	// is used for incoming piece requests.
 	struct TORRENT_EXPORT peer_request
 	{
 		// the index of the piece in which the range starts.
diff --git a/include/libtorrent/ptime.hpp b/include/libtorrent/ptime.hpp
index fcca0c0ec..28edacca8 100644
--- a/include/libtorrent/ptime.hpp
+++ b/include/libtorrent/ptime.hpp
@@ -57,7 +57,9 @@ namespace libtorrent
 	// libtorrent time_duration type
 	struct TORRENT_EXPORT time_duration
 	{
+		// hidden
 		time_duration() {}
+
 		time_duration operator/(int rhs) const { return time_duration(diff / rhs); }
 		explicit time_duration(boost::int64_t d) : diff(d) {}
 		time_duration& operator-=(time_duration const& c) { diff -= c.diff; return *this; }
@@ -73,8 +75,10 @@ namespace libtorrent
 	// This type represents a point in time.
 	struct TORRENT_EXPORT ptime
 	{
+		// hidden
 		ptime() {}
 		explicit ptime(boost::uint64_t t): time(t) {}
+
 		ptime& operator+=(time_duration rhs) { time += rhs.diff; return *this; }
 		ptime& operator-=(time_duration rhs) { time -= rhs.diff; return *this; }
 
@@ -87,40 +91,28 @@ namespace libtorrent
 	// hidden
 	inline bool operator>(ptime lhs, ptime rhs)
 	{ return lhs.time > rhs.time; }
-	// hidden
 	inline bool operator>=(ptime lhs, ptime rhs)
 	{ return lhs.time >= rhs.time; }
-	// hidden
 	inline bool operator<=(ptime lhs, ptime rhs)
 	{ return lhs.time <= rhs.time; }
-	// hidden
 	inline bool operator<(ptime lhs, ptime rhs)
 	{ return lhs.time < rhs.time; }
-	// hidden
 	inline bool operator!=(ptime lhs, ptime rhs)
 	{ return lhs.time != rhs.time;}
-	// hidden
 	inline bool operator==(ptime lhs, ptime rhs)
 	{ return lhs.time == rhs.time;}
-	// hidden
 	inline bool operator==(time_duration lhs, time_duration rhs)
 	{ return lhs.diff == rhs.diff; }
-	// hidden
 	inline bool operator<(time_duration lhs, time_duration rhs)
 	{ return lhs.diff < rhs.diff; }
-	// hidden
 	inline bool operator<=(time_duration lhs, time_duration rhs)
 	{ return lhs.diff <= rhs.diff; }
-	// hidden
 	inline bool operator>(time_duration lhs, time_duration rhs)
 	{ return lhs.diff > rhs.diff; }
-	// hidden
 	inline bool operator>=(time_duration lhs, time_duration rhs)
 	{ return lhs.diff >= rhs.diff; }
-	// hidden
 	inline time_duration operator*(time_duration lhs, int rhs)
 	{ return time_duration(boost::int64_t(lhs.diff * rhs)); }
-	// hidden
 	inline time_duration operator*(int lhs, time_duration rhs)
 	{ return time_duration(boost::int64_t(lhs * rhs.diff)); }
 
diff --git a/include/libtorrent/session.hpp b/include/libtorrent/session.hpp
index 6469f8cb0..cde629828 100644
--- a/include/libtorrent/session.hpp
+++ b/include/libtorrent/session.hpp
@@ -261,6 +261,7 @@ namespace libtorrent
 		// is on by default. See add_torrent_params_.
 		void post_torrent_updates();
 
+		// internal
 		io_service& get_io_service();
 
 		// ``find_torrent()`` looks for a torrent with the given info-hash. In case there
@@ -523,17 +524,17 @@ namespace libtorrent
 		void load_asnum_db(char const* file);
 		void load_country_db(char const* file);
 		int as_for_ip(address const& addr);
+#ifndef TORRENT_NO_DEPRECATE
 #if TORRENT_USE_WSTRING
 		// all wstring APIs are deprecated since 0.16.11
 		// instead, use the wchar -> utf8 conversion functions
 		// and pass in utf8 strings
-#ifndef TORRENT_NO_DEPRECATE
 		TORRENT_DEPRECATED_PREFIX
 		void load_country_db(wchar_t const* file) TORRENT_DEPRECATED;
 		TORRENT_DEPRECATED_PREFIX
 		void load_asnum_db(wchar_t const* file) TORRENT_DEPRECATED;
-#endif // TORRENT_NO_DEPRECATE
 #endif // TORRENT_USE_WSTRING
+#endif // TORRENT_NO_DEPRECATE
 #endif // TORRENT_DISABLE_GEO_IP
 
 #ifndef TORRENT_NO_DEPRECATE
diff --git a/include/libtorrent/session_status.hpp b/include/libtorrent/session_status.hpp
index 6777699ef..47368586c 100644
--- a/include/libtorrent/session_status.hpp
+++ b/include/libtorrent/session_status.hpp
@@ -40,18 +40,43 @@ POSSIBILITY OF SUCH DAMAGE.
 namespace libtorrent
 {
 
-	struct dht_lookup
+	// holds statistics about a current dht_lookup operation.
+	// a DHT lookup is the travesal of nodes, looking up a
+	// set of target nodes in the DHT for retrieving and possibly
+	// storing information in the DHT
+	struct TORRENT_EXPORT dht_lookup
 	{
+		// string literal indicating which kind of lookup this is
 		char const* type;
+
+		// the number of outstanding request to individual nodes
+		// this lookup has right now
 		int outstanding_requests;
+
+		// the total number of requests that have timed out so far
+		// for this lookup
 		int timeouts;
+
+		// the total number of responses we have received for this
+		// lookup so far for this lookup
 		int responses;
+
+		// the branch factor for this lookup. This is the number of
+		// nodes we keep outstanding requests to in parallel by default.
+		// when nodes time out we may increase this.
 		int branch_factor;
+
+		// the number of nodes left that could be queries for this
+		// lookup. Many of these are likely to be part of the trail
+		// while performing the lookup and would never end up actually
+		// being queried.
 		int nodes_left;
+
 		// the number of seconds ago the
 		// last message was sent that's still
 		// outstanding
 		int last_sent;
+
 		// the number of outstanding requests
 		// that have exceeded the short timeout
 		// and are considered timed out in the
@@ -60,24 +85,31 @@ namespace libtorrent
 		int first_timeout;
 	};
 
-	struct dht_routing_bucket
+	// holds dht routing table stats
+	struct TORRENT_EXPORT dht_routing_bucket
 	{
+		// the total number of nodes and replacement nodes
+		// in the routing table
 		int num_nodes;
 		int num_replacements;
+
 		// number of seconds since last activity
 		int last_active;
 	};
 
-	struct utp_status
+	// holds counters and gauges for the uTP sockets
+	struct TORRENT_EXPORT utp_status
 	{
-		// gauges
+		// gauges. These are snapshots of the number of
+		// uTP sockets in each respective state
 		int num_idle;
 		int num_syn_sent;
 		int num_connected;
 		int num_fin_sent;
 		int num_close_wait;
 
-		// counters
+		// counters. These are monotonically increasing
+		// and cumulative counters for their respective event.
 		boost::uint64_t packet_loss;
 		boost::uint64_t timeout;
 		boost::uint64_t packets_in;
@@ -92,6 +124,7 @@ namespace libtorrent
 		boost::uint64_t redundant_pkts_in;
 	};
 
+	// contains session wide state and counters
 	struct TORRENT_EXPORT session_status
 	{
 		// false as long as no incoming connections have been
diff --git a/include/libtorrent/settings.hpp b/include/libtorrent/settings.hpp
index b31067df7..e09e24e95 100644
--- a/include/libtorrent/settings.hpp
+++ b/include/libtorrent/settings.hpp
@@ -41,9 +41,12 @@ namespace libtorrent
 	struct lazy_entry;
 	class entry;
 
-	enum { std_string, character, integer
-		, floating_point, boolean, size_integer
-		, time_integer };
+	// internal
+	enum struct_field_type_t
+	{
+		std_string, character, integer, floating_point,
+		boolean, size_integer, time_integer
+	};
 
 	// this is used to map struct entries
 	// to names in a bencoded dictionary to
diff --git a/include/libtorrent/sha1_hash.hpp b/include/libtorrent/sha1_hash.hpp
index fd5d69113..0547f809f 100644
--- a/include/libtorrent/sha1_hash.hpp
+++ b/include/libtorrent/sha1_hash.hpp
@@ -69,7 +69,7 @@ namespace libtorrent
 		enum { number_size = 20 };
 	public:
 		// the number of bytes of the number
-		enum { size = number_size };
+		static const int size = number_size;
 
 		// constructs an all-sero sha1-hash
 		sha1_hash() { clear(); }
@@ -258,9 +258,10 @@ namespace libtorrent
 		typedef const unsigned char* const_iterator;
 		typedef unsigned char* iterator;
 
+		// start and end iterators for the hash. The value type
+		// of these iterators is ``unsigned char``.
 		const_iterator begin() const { return m_number; }
 		const_iterator end() const { return m_number+number_size; }
-
 		iterator begin() { return m_number; }
 		iterator end() { return m_number+number_size; }
 
diff --git a/include/libtorrent/storage.hpp b/include/libtorrent/storage.hpp
index 23854e058..073504fce 100644
--- a/include/libtorrent/storage.hpp
+++ b/include/libtorrent/storage.hpp
@@ -152,15 +152,7 @@ namespace libtorrent
 		, std::vector<std::pair<size_type, std::time_t> > const& sizes
 		, bool compact_mode
 		, std::string* error = 0);
-/*
-	struct TORRENT_EXTRA_EXPORT file_allocation_failed: std::exception
-	{
-		file_allocation_failed(const char* error_msg): m_msg(error_msg) {}
-		virtual const char* what() const throw() { return m_msg.c_str(); }
-		virtual ~file_allocation_failed() throw() {}
-		std::string m_msg;
-	};
-*/
+
 	struct TORRENT_EXTRA_EXPORT partial_hash
 	{
 		partial_hash(): offset(0) {}
@@ -190,13 +182,14 @@ namespace libtorrent
 	// compact allocation mode it won't).
 	// 
 	// libtorrent comes with two built-in storage implementations; ``default_storage``
-	// and ``disabled_storage``. Their constructor functions are called ``default_storage_constructor``
+	// and ``disabled_storage``. Their constructor functions are called default_storage_constructor()
 	// and ``disabled_storage_constructor`` respectively. The disabled storage does
 	// just what it sounds like. It throws away data that's written, and it
 	// reads garbage. It's useful mostly for benchmarking and profiling purpose.
 	//
 	struct TORRENT_EXPORT storage_interface
 	{
+		// hidden
 		storage_interface(): m_disk_pool(0), m_settings(0) {}
 
 		// This function is called when the storage is to be initialized. The default storage
@@ -247,6 +240,8 @@ namespace libtorrent
 		// negative return value indicates an error
 		virtual int write(const char* buf, int slot, int offset, int size) = 0;
 
+		// returns the offset on the physical storage medium for the
+		// byte at offset ``offset`` in slot ``slot``.
 		virtual size_type physical_offset(int slot, int offset) = 0;
 
 		// This function is optional. It is supposed to return the first piece, starting at
@@ -395,6 +390,8 @@ namespace libtorrent
 	public:
 		default_storage(file_storage const& fs, file_storage const* mapped, std::string const& path
 			, file_pool& fp, std::vector<boost::uint8_t> const& file_prio);
+
+		// hidden
 		~default_storage();
 
 #ifndef TORRENT_NO_DEPRECATE
diff --git a/include/libtorrent/storage_defs.hpp b/include/libtorrent/storage_defs.hpp
index 3a33e2abd..0308c7daf 100644
--- a/include/libtorrent/storage_defs.hpp
+++ b/include/libtorrent/storage_defs.hpp
@@ -65,10 +65,15 @@ namespace libtorrent
 	typedef boost::function<storage_interface*(file_storage const&, file_storage const*
 		, std::string const&, file_pool&, std::vector<boost::uint8_t> const&)> storage_constructor_type;
 
+	// the constructor function for the regular file storage. This is the
+	// default value for add_torrent_params::storage.
 	TORRENT_EXPORT storage_interface* default_storage_constructor(
 		file_storage const&, file_storage const* mapped, std::string const&, file_pool&
 		, std::vector<boost::uint8_t> const&);
 
+	// the constructor function for the disabled storage. This can be used for
+	// testing and benchmarking. It will throw away any data written to
+	// it and return garbage for anything read from it.
 	TORRENT_EXPORT storage_interface* disabled_storage_constructor(
 		file_storage const&, file_storage const* mapped, std::string const&, file_pool&
 		, std::vector<boost::uint8_t> const&);
diff --git a/include/libtorrent/torrent_handle.hpp b/include/libtorrent/torrent_handle.hpp
index fe36e79e6..13146470c 100644
--- a/include/libtorrent/torrent_handle.hpp
+++ b/include/libtorrent/torrent_handle.hpp
@@ -421,6 +421,11 @@ namespace libtorrent
 		void remove_http_seed(std::string const& url) const;
 		std::set<std::string> http_seeds() const;
 
+		// add the specified extension to this torrent. The ``ext`` argument is
+		// a function that will be called from within libtorrent's context
+		// passing in the internal torrent object and the specified userdata
+		// pointer. The function is expected to return a shared pointer to
+		// a torrent_plugin instance.
 		void add_extension(boost::function<boost::shared_ptr<torrent_plugin>(torrent*, void*)> const& ext
 			, void* userdata = 0);
 
@@ -499,18 +504,24 @@ namespace libtorrent
 		// to peers again, as normal.
 		void force_recheck() const;
 
-		enum save_resume_flags_t { flush_disk_cache = 1, save_info_dict = 2 };
+		// flags used in the save_resume_data call to control additional
+		// actions or fields to save.
+		enum save_resume_flags_t
+		{
+			// the disk cache will be flushed before creating the resume data. This avoids a problem with
+			// file timestamps in the resume data in case the cache hasn't been flushed yet.
+			flush_disk_cache = 1,
+
+			// the resume data will contain the metadata
+			// from the torrent file as well. This is default for any torrent that's added without a torrent
+			// file (such as a magnet link or a URL).
+			save_info_dict = 2
+		};
 
 		// ``save_resume_data()`` generates fast-resume data and returns it as an entry. This entry
 		// is suitable for being bencoded. For more information about how fast-resume works, see fast-resume_.
 		// 
-		// The ``flags`` argument is a bitmask of flags ORed together. If the flag ``torrent_handle::flush_cache``
-		// is set, the disk cache will be flushed before creating the resume data. This avoids a problem with
-		// file timestamps in the resume data in case the cache hasn't been flushed yet.
-		// 
-		// If the flag ``torrent_handle::save_info_dict`` is set, the resume data will contain the metadata
-		// from the torrent file as well. This is default for any torrent that's added without a torrent
-		// file (such as a magnet link or a URL).
+		// The ``flags`` argument is a bitmask of flags ORed together. see save_resume_flags_t
 		// 
 		// This operation is asynchronous, ``save_resume_data`` will return immediately. The resume data
 		// is delivered when it's done through an save_resume_data_alert.
@@ -977,8 +988,8 @@ namespace libtorrent
 		// when either a file_renamed_alert or file_rename_failed_alert is posted.
 		void rename_file(int index, std::string const& new_name) const;
 
-#if TORRENT_USE_WSTRING
 #ifndef TORRENT_NO_DEPRECATE
+#if TORRENT_USE_WSTRING
 		// all wstring APIs are deprecated since 0.16.11
 		// instead, use the wchar -> utf8 conversion functions
 		// and pass in utf8 strings
@@ -986,8 +997,8 @@ namespace libtorrent
 		void move_storage(std::wstring const& save_path, int flags = 0) const TORRENT_DEPRECATED;
 		TORRENT_DEPRECATED_PREFIX
 		void rename_file(int index, std::wstring const& new_name) const TORRENT_DEPRECATED;
-#endif // TORRENT_NO_DEPRECATE
 #endif // TORRENT_USE_WSTRING
+#endif // TORRENT_NO_DEPRECATE
 
 		// Enables or disabled super seeding/initial seeding for this torrent. The torrent
 		// needs to be a seed for this to take effect.
@@ -1018,10 +1029,6 @@ namespace libtorrent
 			: m_torrent(t)
 		{}
 
-#if defined TORRENT_DEBUG && !defined TORRENT_DISABLE_INVARIANT_CHECKS
-		void check_invariant() const;
-#endif
-
 		boost::weak_ptr<torrent> m_torrent;
 
 	};
@@ -1043,64 +1050,69 @@ namespace libtorrent
 		enum state_t
 		{
 			// The torrent is in the queue for being checked. But there
-			// currently is another torrent that are being checked.    
-			// This torrent will wait for its turn.                    
+			// currently is another torrent that are being checked.
+			// This torrent will wait for its turn.
 			queued_for_checking,
 
 			// The torrent has not started its download yet, and is
-			// currently checking existing files.                  
+			// currently checking existing files.
 			checking_files,
 
-			// The torrent is trying to download metadata from peers. 
+			// The torrent is trying to download metadata from peers.
 			// This assumes the metadata_transfer extension is in use.
 			downloading_metadata,
 
-			// The torrent is being downloaded. This is the state     
+			// The torrent is being downloaded. This is the state
 			// most torrents will be in most of the time. The progress
-			// meter will tell how much of the files that has been    
-			// downloaded.                                            
+			// meter will tell how much of the files that has been
+			// downloaded.
 			downloading,
 
-			// In this state the torrent has finished downloading but 
+			// In this state the torrent has finished downloading but
 			// still doesn't have the entire torrent. i.e. some pieces
-			// are filtered and won't get downloaded.                 
+			// are filtered and won't get downloaded.
 			finished,
 
 			// In this state the torrent has finished downloading and
-			// is a pure seeder.                                     
+			// is a pure seeder.
 			seeding,
 
 			// If the torrent was started in full allocation mode, this
-			// indicates that the (disk) storage for the torrent is    
-			// allocated.                                              
+			// indicates that the (disk) storage for the torrent is
+			// allocated.
 			allocating,
 
 			// The torrent is currently checking the fastresume data and
-			// comparing it to the files on disk. This is typically     
-			// completed in a fraction of a second, but if you add a    
-			// large number of torrents at once, they will queue up.    
+			// comparing it to the files on disk. This is typically
+			// completed in a fraction of a second, but if you add a
+			// large number of torrents at once, they will queue up.
 			checking_resume_data
 		};
 		
-		// may be set to an error message describing why the torrent was paused, in
-		// case it was paused by an error. If the torrent is not paused or if it's paused but
-		// not because of an error, this string is empty.
+		// may be set to an error message describing why the torrent
+		// was paused, in case it was paused by an error. If the torrent
+		// is not paused or if it's paused but not because of an error,
+		// this string is empty.
 		std::string error;
 
 		// the path to the directory where this torrent's files are stored.
-		// It's typically the path as was given to async_add_torrent() or add_torrent() when this torrent
-		// was started. This field is only included if the torrent status is queried with
+		// It's typically the path as was given to async_add_torrent() or
+		// add_torrent() when this torrent was started. This field is only
+		// included if the torrent status is queried with
 		// ``torrent_handle::query_save_path``.
 		std::string save_path;
 
-		// the name of the torrent. Typically this is derived from the .torrent file.
-		// In case the torrent was started without metadata, and hasn't completely received it yet,
-		// it returns the name given to it when added to the session. See ``session::add_torrent``.
-		// This field is only included if the torrent status is queried with ``torrent_handle::query_name``.
+		// the name of the torrent. Typically this is derived from the
+		// .torrent file. In case the torrent was started without metadata,
+		// and hasn't completely received it yet, it returns the name given
+		// to it when added to the session. See ``session::add_torrent``.
+		// This field is only included if the torrent status is queried
+		// with ``torrent_handle::query_name``.
 		std::string name;
 
 		// set to point to the ``torrent_info`` object for this torrent. It's
-		// only included if the torrent status is queried with ``torrent_handle::query_torrent_file``.
+		// only included if the torrent status is queried with
+		// ``torrent_handle::query_torrent_file``.
 		boost::intrusive_ptr<const torrent_info> torrent_file;
 
 		// the time until the torrent will announce itself to the tracker.
diff --git a/include/libtorrent/torrent_info.hpp b/include/libtorrent/torrent_info.hpp
index 5bf73684e..0aef43f96 100644
--- a/include/libtorrent/torrent_info.hpp
+++ b/include/libtorrent/torrent_info.hpp
@@ -331,30 +331,30 @@ namespace libtorrent
 		torrent_info(lazy_entry const& torrent_file, int flags = 0);
 		torrent_info(char const* buffer, int size, int flags = 0);
 		torrent_info(std::string const& filename, int flags = 0);
+#ifndef TORRENT_NO_DEPRECATE
 #if TORRENT_USE_WSTRING
 		// all wstring APIs are deprecated since 0.16.11
 		// instead, use the wchar -> utf8 conversion functions
 		// and pass in utf8 strings
-#ifndef TORRENT_NO_DEPRECATE
 		TORRENT_DEPRECATED_PREFIX
 		torrent_info(std::wstring const& filename, int flags = 0) TORRENT_DEPRECATED;
-#endif // TORRENT_NO_DEPRECATE
 #endif // TORRENT_USE_WSTRING
+#endif // TORRENT_NO_DEPRECATE
 #endif
 		torrent_info(torrent_info const& t, int flags = 0);
 		torrent_info(sha1_hash const& info_hash, int flags = 0);
 		torrent_info(lazy_entry const& torrent_file, error_code& ec, int flags = 0);
 		torrent_info(char const* buffer, int size, error_code& ec, int flags = 0);
 		torrent_info(std::string const& filename, error_code& ec, int flags = 0);
+#ifndef TORRENT_NO_DEPRECATE
 #if TORRENT_USE_WSTRING
 		// all wstring APIs are deprecated since 0.16.11
 		// instead, use the wchar -> utf8 conversion functions
 		// and pass in utf8 strings
-#ifndef TORRENT_NO_DEPRECATE
 		TORRENT_DEPRECATED_PREFIX
 		torrent_info(std::wstring const& filename, error_code& ec, int flags = 0) TORRENT_DEPRECATED;
-#endif // TORRENT_NO_DEPRECATE
 #endif // TORRENT_USE_WSTRING
+#endif // TORRENT_NO_DEPRECATE
 
 		// frees all storage associated with this torrent_info object
 		~torrent_info();
@@ -392,15 +392,15 @@ namespace libtorrent
 			copy_on_write();
 			m_files.rename_file(index, new_filename);
 		}
+#ifndef TORRENT_NO_DEPRECATE
 #if TORRENT_USE_WSTRING
 		// all wstring APIs are deprecated since 0.16.11
 		// instead, use the wchar -> utf8 conversion functions
 		// and pass in utf8 strings
-#ifndef TORRENT_NO_DEPRECATE
 		TORRENT_DEPRECATED_PREFIX
 		void rename_file(int index, std::wstring const& new_filename) TORRENT_DEPRECATED;
-#endif // TORRENT_NO_DEPRECATE
 #endif // TORRENT_USE_WSTRING
+#endif // TORRENT_NO_DEPRECATE
 
 		// Remaps the file storage to a new file layout. This can be used to, for instance,
 		// download all data in a torrent to a single file, or to a number of fixed size
diff --git a/include/libtorrent/utp_stream.hpp b/include/libtorrent/utp_stream.hpp
index 90381a9c0..108fd8502 100644
--- a/include/libtorrent/utp_stream.hpp
+++ b/include/libtorrent/utp_stream.hpp
@@ -119,7 +119,8 @@ namespace libtorrent
 */
 
 // internal: the different kinds of uTP packets
-enum { ST_DATA = 0, ST_FIN, ST_STATE, ST_RESET, ST_SYN, NUM_TYPES };
+enum utp_socket_state_t
+{ ST_DATA, ST_FIN, ST_STATE, ST_RESET, ST_SYN, NUM_TYPES };
 
 struct utp_header
 {
diff --git a/src/torrent_handle.cpp b/src/torrent_handle.cpp
index 3280ef86c..97242ad46 100644
--- a/src/torrent_handle.cpp
+++ b/src/torrent_handle.cpp
@@ -266,12 +266,6 @@ namespace libtorrent
 	}
 #endif
 
-#if defined TORRENT_DEBUG && !defined TORRENT_DISABLE_INVARIANT_CHECKS
-	void torrent_handle::check_invariant() const
-	{}
-
-#endif
-
 	sha1_hash torrent_handle::info_hash() const
 	{
 		INVARIANT_CHECK;