diff --git a/include/libtorrent/disk_io_thread.hpp b/include/libtorrent/disk_io_thread.hpp
index ccce2bb56..b5c2a0dc6 100644
--- a/include/libtorrent/disk_io_thread.hpp
+++ b/include/libtorrent/disk_io_thread.hpp
@@ -167,6 +167,8 @@ namespace libtorrent
 	// points to a disk buffer
 	bool operation_has_buffer(disk_io_job const& j);
 
+	// this struct holds a number of statistics counters
+	// relevant for the disk io thread and disk cache.
 	struct TORRENT_EXPORT cache_status
 	{
 		cache_status()
@@ -205,7 +207,6 @@ namespace libtorrent
 		// The ratio (``blocks_written`` - ``writes``) / ``blocks_written`` represents
 		// the number of saved write operations per total write operations. i.e. a kind
 		// of cache hit ratio for the write cahe.
-
 		size_type writes;
 
 		// the number of blocks that were requested from the
@@ -221,6 +222,8 @@ namespace libtorrent
 		// the number of read operations used
 		size_type reads;
 
+		// the number of bytes waiting, in the disk job queue, to be written
+		// or inserted into the disk cache
 		mutable size_type queued_bytes;
 
 		// the number of 16 KiB blocks currently in the disk cache (both read and write).
@@ -260,12 +263,20 @@ namespace libtorrent
 		// the number of jobs in the job queue.
 		int job_queue_length;
 
+		// the number of milliseconds spent in all disk jobs, and specific ones
+		// since the start of the session. Times are specified in milliseconds
 		boost::uint32_t cumulative_job_time;
 		boost::uint32_t cumulative_read_time;
 		boost::uint32_t cumulative_write_time;
 		boost::uint32_t cumulative_hash_time;
 		boost::uint32_t cumulative_sort_time;
+
+		// the number of bytes that had to be read back from disk because
+		// they were flushed before the SHA-1 hash got to hash them. If this
+		// is large, a larger cache could significantly improve performance
 		int total_read_back;
+
+		// number of read jobs in the disk job queue
 		int read_queue_size;
 	};
 	
diff --git a/include/libtorrent/escape_string.hpp b/include/libtorrent/escape_string.hpp
index b2ea6a498..c0b5606f2 100644
--- a/include/libtorrent/escape_string.hpp
+++ b/include/libtorrent/escape_string.hpp
@@ -71,8 +71,22 @@ namespace libtorrent
 	TORRENT_EXTRA_EXPORT int hex_to_int(char in);
 
 	TORRENT_EXTRA_EXPORT bool is_hex(char const *in, int len);
+
+	// converts (binary) the string ``s`` to hexadecimal representation and
+	// returns it.
 	TORRENT_EXPORT std::string to_hex(std::string const& s);
+
+	// converts the binary buffer [``in``, ``in`` + len) to hexadecimal
+	// and prints it to the buffer ``out``. The caller is responsible for
+	// making sure the buffer pointed to by ``out`` is large enough,
+	// i.e. has at least len * 2 bytes of space.
 	TORRENT_EXPORT void to_hex(char const *in, int len, char* out);
+
+	// converts the buffer [``in``, ``in`` + len) from hexadecimal to
+	// binary. The binary output is written to the buffer pointed to
+	// by ``out``. The caller is responsible for making sure the buffer
+	// at ``out`` has enough space for the result to be written to, i.e.
+	// (len + 1) / 2 bytes.
 	TORRENT_EXPORT bool from_hex(char const *in, int len, char* out);
 
 #if defined TORRENT_WINDOWS && TORRENT_USE_WSTRING
diff --git a/include/libtorrent/session_settings.hpp b/include/libtorrent/session_settings.hpp
index ca3170b97..616de5f1f 100644
--- a/include/libtorrent/session_settings.hpp
+++ b/include/libtorrent/session_settings.hpp
@@ -797,12 +797,10 @@ namespace libtorrent
 		// to 0 on all platforms except windows.
 		int max_sparse_regions;
 
-#ifndef TORRENT_DISABLE_MLOCK
 		// if lock disk cache is set to true the disk cache
 		// that's in use, will be locked in physical memory, preventing it from
 		// being swapped out.
 		bool lock_disk_cache;
-#endif
 
 		// the number of piece requests we will reject in a row
 		// while a peer is choked before the peer is considered abusive and is
diff --git a/include/libtorrent/sha1_hash.hpp b/include/libtorrent/sha1_hash.hpp
index 0d6cc5db3..f614531c8 100644
--- a/include/libtorrent/sha1_hash.hpp
+++ b/include/libtorrent/sha1_hash.hpp
@@ -66,9 +66,9 @@ namespace libtorrent
 	// peer IDs, node IDs etc.
 	class TORRENT_EXPORT sha1_hash
 	{
-		// the number of bytes of the number
 		enum { number_size = 20 };
 	public:
+		// the number of bytes of the number
 		enum { size = number_size };
 
 		// constructs an all-sero sha1-hash
@@ -279,6 +279,8 @@ namespace libtorrent
 	typedef sha1_hash sha1_hash;
 
 #if TORRENT_USE_IOSTREAM
+
+	// print a sha1_hash object to an ostream as 40 hexadecimal digits
 	inline std::ostream& operator<<(std::ostream& os, sha1_hash const& peer)
 	{
 		char out[41];
@@ -286,6 +288,7 @@ namespace libtorrent
 		return os << out;
 	}
 
+	// read 40 hexadecimal digits from an istream into a sha1_hash
 	inline std::istream& operator>>(std::istream& is, sha1_hash& peer)
 	{
 		char hex[40];
diff --git a/include/libtorrent/torrent_handle.hpp b/include/libtorrent/torrent_handle.hpp
index 98890aef4..cb0758527 100644
--- a/include/libtorrent/torrent_handle.hpp
+++ b/include/libtorrent/torrent_handle.hpp
@@ -221,6 +221,8 @@ namespace libtorrent
 		friend class torrent;
 		friend std::size_t hash_value(torrent_handle const& th);
 
+		// constructs a torrent handle that does not refer to a torrent.
+		// i.e. is_valid() will return false.
 		torrent_handle() {}
 
 		// flags for add_piece().
diff --git a/include/libtorrent/torrent_info.hpp b/include/libtorrent/torrent_info.hpp
index 3db87ebc6..18c330843 100644
--- a/include/libtorrent/torrent_info.hpp
+++ b/include/libtorrent/torrent_info.hpp
@@ -352,6 +352,7 @@ namespace libtorrent
 #endif // TORRENT_NO_DEPRECATE
 #endif // TORRENT_USE_WSTRING
 
+		// frees all storage associated with this torrent_info object
 		~torrent_info();
 
 		// The file_storage object contains the information on how to map the pieces to
diff --git a/include/libtorrent/utp_stream.hpp b/include/libtorrent/utp_stream.hpp
index b2ee966ca..fb7e109c4 100644
--- a/include/libtorrent/utp_stream.hpp
+++ b/include/libtorrent/utp_stream.hpp
@@ -54,7 +54,7 @@ namespace libtorrent
 {
 	struct utp_socket_manager;
 
-	// some MTU and protocol header sizes constants
+	// internal: some MTU and protocol header sizes constants
 	enum
 	{
 		TORRENT_IPV4_HEADER = 20,
@@ -68,7 +68,7 @@ namespace libtorrent
 		TORRENT_INET_MAX_MTU = 0xffff
 	};
 
-	// the point of the bif_endian_int is two-fold
+	// internal: the point of the bif_endian_int is two-fold
 	// one purpuse is to not have any alignment requirements
 	// so that any byffer received from the network can be cast
 	// to it and read as an integer of various sizes without
@@ -118,22 +118,23 @@ namespace libtorrent
 
 */
 
-	enum { ST_DATA = 0, ST_FIN, ST_STATE, ST_RESET, ST_SYN, NUM_TYPES };
+// internal: the different kinds of uTP packets
+enum { ST_DATA = 0, ST_FIN, ST_STATE, ST_RESET, ST_SYN, NUM_TYPES };
 
-	struct utp_header
-	{
-		unsigned char type_ver;
-		unsigned char extension;
-		be_uint16 connection_id;
-		be_uint32 timestamp_microseconds;
-		be_uint32 timestamp_difference_microseconds;
-		be_uint32 wnd_size;
-		be_uint16 seq_nr;
-		be_uint16 ack_nr;
+struct utp_header
+{
+	unsigned char type_ver;
+	unsigned char extension;
+	be_uint16 connection_id;
+	be_uint32 timestamp_microseconds;
+	be_uint32 timestamp_difference_microseconds;
+	be_uint32 wnd_size;
+	be_uint16 seq_nr;
+	be_uint16 ack_nr;
 
-		int get_type() const { return type_ver >> 4; }
-		int get_version() const { return type_ver & 0xf; }
-	};
+	int get_type() const { return type_ver >> 4; }
+	int get_version() const { return type_ver & 0xf; }
+};
 
 struct utp_socket_impl;
 
diff --git a/src/session.cpp b/src/session.cpp
index ee3c94a3a..d5e2cdec7 100644
--- a/src/session.cpp
+++ b/src/session.cpp
@@ -1258,9 +1258,7 @@ namespace libtorrent
 #else
 		, max_sparse_regions(0)
 #endif
-#ifndef TORRENT_DISABLE_MLOCK
 		, lock_disk_cache(false)
-#endif
 		, max_rejects(50)
 		, recv_socket_buffer_size(0)
 		, send_socket_buffer_size(0)