diff --git a/include/libtorrent/ptime.hpp b/include/libtorrent/ptime.hpp
index 226a2dd12..01caabbf5 100644
--- a/include/libtorrent/ptime.hpp
+++ b/include/libtorrent/ptime.hpp
@@ -60,13 +60,18 @@ namespace libtorrent
 		// hidden
 		time_duration() {}
 
+		// all operators have the same semantics as a 64 bit signed integer
 		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; }
-		time_duration& operator+=(time_duration const& c) { diff += c.diff; return *this; }
+		time_duration& operator-=(time_duration const& c)
+		{ diff -= c.diff; return *this; }
+		time_duration& operator+=(time_duration const& c)
+		{ diff += c.diff; return *this; }
 		time_duration& operator*=(int v) { diff *= v; return *this; }
-		time_duration operator+(time_duration const& c) { return time_duration(diff + c.diff); }
-		time_duration operator-(time_duration const& c) { return time_duration(diff - c.diff); }
+		time_duration operator+(time_duration const& c)
+		{ return time_duration(diff + c.diff); }
+		time_duration operator-(time_duration const& c)
+		{ return time_duration(diff - c.diff); }
 
 		// internal
 		boost::int64_t diff;
@@ -79,6 +84,7 @@ namespace libtorrent
 		ptime() {}
 		explicit ptime(boost::uint64_t t): time(t) {}
 
+		// these operators have the same semantics as signed 64 bit integers
 		ptime& operator+=(time_duration rhs) { time += rhs.diff; return *this; }
 		ptime& operator-=(time_duration rhs) { time -= rhs.diff; return *this; }
 
@@ -86,9 +92,10 @@ namespace libtorrent
 		boost::uint64_t time;
 	};
 
+	// returns true of the time duration is less than 0
 	inline bool is_negative(time_duration dt) { return dt.diff < 0; }
 
-	// hidden
+	// all operators have the same semantics as signed 64 bit integers
 	inline bool operator>(ptime lhs, ptime rhs)
 	{ return lhs.time > rhs.time; }
 	inline bool operator>=(ptime lhs, ptime rhs)
@@ -115,7 +122,6 @@ namespace libtorrent
 	{ return time_duration(boost::int64_t(lhs.diff * rhs)); }
 	inline time_duration operator*(int lhs, time_duration rhs)
 	{ return time_duration(boost::int64_t(lhs * rhs.diff)); }
-
 	inline time_duration operator-(ptime lhs, ptime rhs)
 	{ return time_duration(lhs.time - rhs.time); }
 	inline ptime operator+(ptime lhs, time_duration rhs)
diff --git a/include/libtorrent/session_settings.hpp b/include/libtorrent/session_settings.hpp
index 6589af13d..53f6ef639 100644
--- a/include/libtorrent/session_settings.hpp
+++ b/include/libtorrent/session_settings.hpp
@@ -452,6 +452,8 @@ namespace libtorrent
 		bool auto_upload_slots_rate_based;
 #endif
 
+		// the different choking algorithms available. Set
+		// session_settings::choking_algorithm to one of these
 		enum choking_algorithm_t
 		{
 			// the traditional choker with a fixed number of unchoke
@@ -485,6 +487,8 @@ namespace libtorrent
 		// and ``auto_upload_slots_rate_based``. For options, see choking_algorithm_t.
 		int choking_algorithm;
 
+		// the different choking algorithms available when seeding. Set
+		// session_settings::seed_choking_algorithm to one of these
 		enum seed_choking_algorithm_t
 		{
 			// round-robins the peers that are unchoked when seeding. This
@@ -558,6 +562,9 @@ namespace libtorrent
 		// the cache at the time.
 		int explicit_cache_interval;
 
+		// the buffer modes to use for reading and writing. Set
+		// session_settings::disk_io_read_mode and disk_io_write_mode to one of
+		// these.
 		enum io_buffer_mode_t
 		{
 			// This is the default and files are opened normally, with the OS caching
@@ -584,6 +591,12 @@ namespace libtorrent
 		int disk_io_write_mode;
 		int disk_io_read_mode;
 
+		// when set to true, instead of issuing multiple adjacent reads or writes
+		// to the disk, allocate a larger buffer, copy all writes into it and
+		// issue a single write. For reads, read into a larger buffer and copy
+		// the buffer into the smaller individual read buffers afterwards. This
+		// may save system calls, but will cost in additional memory allocation
+		// and copying.
 		bool coalesce_reads;
 		bool coalesce_writes;
 
@@ -848,6 +861,8 @@ namespace libtorrent
 		// as they leave disk I/O time for other processes.
 		int file_checks_delay_per_block;
 
+		// the disk cache algorithms available. Set
+		// session_settings::disk_cache_algorithm to one of these.
 		enum disk_cache_algo_t
 		{
 			// This
@@ -1228,6 +1243,7 @@ namespace libtorrent
 		// you're doing. Never set it higher than 100.
 		int utp_loss_multiplier;
 
+		// the options for session_settings::mixed_mode_algorithm.
 		enum bandwidth_mixed_algo_t
 		{
 			// disables the mixed mode bandwidth balancing
diff --git a/include/libtorrent/storage.hpp b/include/libtorrent/storage.hpp
index 4e9794c09..545e1365d 100644
--- a/include/libtorrent/storage.hpp
+++ b/include/libtorrent/storage.hpp
@@ -389,8 +389,20 @@ namespace libtorrent
 	class TORRENT_EXPORT default_storage : public storage_interface, boost::noncopyable
 	{
 	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);
+		// constructs the default_storage based on the give file_storage (fs).
+		// ``mapped`` is an optional argument (it may be NULL). If non-NULL it
+		// represents the file mappsing that have been made to the torrent before
+		// adding it. That's where files are supposed to be saved and looked for
+		// on disk. ``save_path`` is the root save folder for this torrent.
+		// ``file_pool`` is the cache of file handles that the storage will use.
+		// All files it opens will ask the file_pool to open them. ``file_prio``
+		// is a vector indicating the priority of files on startup. It may be
+		// an empty vector. Any file whose index is not represented by the vector
+		// (because the vector is too short) are assumed to have priority 1.
+		// this is used to treat files with priority 0 slightly differently.
+		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();
@@ -417,6 +429,8 @@ namespace libtorrent
 		bool verify_resume_data(lazy_entry const& rd, error_code& error);
 		bool write_resume_data(entry& rd) const;
 
+		// if the files in this storage are mapped, returns the mapped
+		// file_storage, otherwise returns the original file_storage object.
 		file_storage const& files() const { return m_mapped_files?*m_mapped_files:m_files; }
 
 	private: