more documentation

include/libtorrent/disk_buffer_holder.hpp

@@ -53,12 +53,31 @@ namespace libtorrent
 	// this buffer has been released, ``buffer()`` will return 0.
 	struct TORRENT_EXPORT disk_buffer_holder
 	{
+		// internal
 		disk_buffer_holder(aux::session_impl& ses, char* buf);
+
+		// construct a buffer holder that will free the held buffer
+		// using a disk buffer pool directly (there's only one
+		// disk_buffer_pool per session)
 		disk_buffer_holder(disk_buffer_pool& disk_pool, char* buf);
+
+		// frees any unreleased disk buffer held by this object
 		~disk_buffer_holder();
+		
+		// return the held disk buffer and clear it from the
+		// holder. The responsibility to free it is passed on
+		// to the caller
 		char* release();
+
+		// return a pointer to the held buffer
 		char* get() const { return m_buf; }
+
+		// set the holder object to hold the specified buffer
+		// (or NULL by default). If it's already holding a
+		// disk buffer, it will first be freed.
 		void reset(char* buf = 0);
+
+		// swap pointers of two disk buffer holders.
 		void swap(disk_buffer_holder& h)
 		{
 			TORRENT_ASSERT(&h.m_disk_pool == &m_disk_pool);
@@ -66,6 +85,8 @@ namespace libtorrent
 		}
 
 		typedef char* (disk_buffer_holder::*unspecified_bool_type)();
+
+		// internal
 		operator unspecified_bool_type() const
 		{ return m_buf == 0? 0: &disk_buffer_holder::release; }
 

include/libtorrent/error_code.hpp

@@ -507,7 +507,11 @@ namespace libtorrent
 		{ return boost::system::error_condition(ev, *this); }
 	};
 
+	// return the instance of the libtorrent_error_category which
+	// maps libtorrent error codes to human readable error messages.
 	TORRENT_EXPORT boost::system::error_category& get_libtorrent_category();
+
+	// returns the error_category for HTTP errors
 	TORRENT_EXPORT boost::system::error_category& get_http_category();
 
 	namespace errors

include/libtorrent/lazy_entry.hpp

@@ -140,6 +140,7 @@ namespace libtorrent
 			none_t, dict_t, list_t, string_t, int_t
 		};
 
+		// internal
 		lazy_entry() : m_begin(0), m_len(0), m_size(0), m_capacity(0), m_type(none_t)
 		{ m_data.start = 0; }
 
@@ -239,6 +240,12 @@ namespace libtorrent
 		boost::int64_t dict_find_int_value(char const* name, boost::int64_t default_val = 0) const;
 		lazy_entry const* dict_find_int(char const* name) const;
 
+		// these functions require that ``this`` is a dictionary.
+		// (this->type() == dict_t). They look for an element with the
+		// specified name in the dictionary. ``dict_find_dict`` only
+		// finds dictionaries and ``dict_find_list`` only finds lists.
+		// if no key with the corresponding value of the right type is
+		// found, NULL is returned.
 		lazy_entry const* dict_find_dict(char const* name) const;
 		lazy_entry const* dict_find_list(char const* name) const;
 
@@ -246,7 +253,8 @@ namespace libtorrent
 		// position ``i`` from the dictionary.
 		std::pair<std::string, lazy_entry const*> dict_at(int i) const;
 
-		// if this is a dictionary, return the number of items in it
+		// requires that ``this`` is a dictionary. return the
+		// number of items in it
 		int dict_size() const
 		{
 			TORRENT_ASSERT(m_type == dict_t);
@@ -266,7 +274,8 @@ namespace libtorrent
 		// internal
 		lazy_entry* list_append();
 
-		// if this is a list, return the item at index ``i``.
+		// requires that ``this`` is a list. return
+		// the item at index ``i``.
 		lazy_entry* list_at(int i)
 		{
 			TORRENT_ASSERT(m_type == list_t);
@@ -276,8 +285,19 @@ namespace libtorrent
 		lazy_entry const* list_at(int i) const
 		{ return const_cast<lazy_entry*>(this)->list_at(i); }
 
+		// these functions require ``this`` to have the type list.
+		// (this->type() == list_t). ``list_string_value_at`` returns
+		// the string at index ``i``. ``list_pstr_at``
+		// returns a pascal_string of the string value at index ``i``.
+		// if the element at ``i`` is not a string, an empty string
+		// is returned.
 		std::string list_string_value_at(int i) const;
 		pascal_string list_pstr_at(int i) const;
+
+		// this function require ``this`` to have the type list.
+		// (this->type() == list_t). returns the integer value at
+		// index ``i``. If the element at ``i`` is not an integer
+		// ``default_val`` is returned, which defaults to 0.
 		boost::int64_t list_int_value_at(int i, boost::int64_t default_val = 0) const;
 
 		// if this is a list, return the number of items in it.

include/libtorrent/session.hpp

@@ -556,11 +556,23 @@ namespace libtorrent
 		void set_ip_filter(ip_filter const& f);
 		ip_filter get_ip_filter() const;
 		
+		// apply port_filter ``f`` to incoming and outgoing peers.
+		// a port filter will reject making outgoing peer connections
+		// to certain remote ports. The main intention is to be able
+		// to avoid triggering certain anti-virus software by connecting
+		// to SMTP, FTP ports.
 		void set_port_filter(port_filter const& f);
+
+		// sets and gets the raw peer ID used by libtorrent. When anonymous
+		// mode is set the peer ID is randomized per peer anyway.
 		void set_peer_id(peer_id const& pid);
-		void set_key(int key);
 		peer_id id() const;
 
+		// sets the key sent to trackers. If it's not set, it is initialized
+		// by libtorrent. The key may be used by the tracker to identify the
+		// peer potentially across you changing your IP.
+		void set_key(int key);
+
 
 		// ``is_listening()`` will tell you whether or not the session has successfully
 		// opened a listening port. If it hasn't, this function will return false, and

include/libtorrent/utf8.hpp

@@ -44,8 +44,29 @@ POSSIBILITY OF SUCH DAMAGE.
 
 namespace libtorrent
 {
-	TORRENT_EXPORT int utf8_wchar(const std::string &utf8, std::wstring &wide);
-	TORRENT_EXPORT int wchar_utf8(const std::wstring &wide, std::string &utf8);
+	enum utf8_conv_result_t
+	{
+		// conversion successful
+		conversion_oK,
+
+		// partial character in source, but hit end
+		source_exhausted,
+
+		// insuff. room in target for conversion
+		target_exhausted,
+
+		// source sequence is illegal/malformed
+		source_illegal
+	};
+
+	// ``utf8_wchar`` converts a UTF-8 string (``utf8``) to a wide character
+	// string (``wide``). ``wchar_utf8`` converts a wide character string
+	// (``wide``) to a UTF-8 string (``utf8``). The return value is one of
+	// the enumeration values from utf8_conv_result_t.
+	TORRENT_EXPORT utf8_conv_result_t utf8_wchar(
+		const std::string &utf8, std::wstring &wide);
+	TORRENT_EXPORT utf8_conv_result_t wchar_utf8(
+		const std::wstring &wide, std::string &utf8);
 }
 #endif // !BOOST_NO_STD_WSTRING
 

src/utf8.cpp

@@ -40,7 +40,7 @@ POSSIBILITY OF SUCH DAMAGE.
 
 namespace libtorrent
 {
-	int utf8_wchar(const std::string &utf8, std::wstring &wide)
+	utf8_conv_result_t utf8_wchar(const std::string &utf8, std::wstring &wide)
 	{
 		// allocate space for worst-case
 		wide.resize(utf8.size());
@@ -69,7 +69,7 @@ namespace libtorrent
 		}
 	}
 
-	int wchar_utf8(const std::wstring &wide, std::string &utf8)
+	utf8_conv_result_t wchar_utf8(const std::wstring &wide, std::string &utf8)
 	{
 		// allocate space for worst-case
 		utf8.resize(wide.size() * 6);