added documentations to headers

docs/gen_reference_doc.py

@@ -113,6 +113,15 @@ def categorize_symbol(name, filename):
 
 	return 'Core'
 
+def suppress_warning(filename, name):
+	f = os.path.split(filename)[1]
+	if f != 'alert_types.hpp': return False
+
+#	if name.endswith('_alert') or name == 'message()':
+	return True
+
+#	return False
+
 def first_item(itr):
 	for i in itr:
 		return i
@@ -285,6 +294,8 @@ def parse_class(lno, lines, filename):
 					funs[-1]['names'].update(current_fun['names'])
 				else:
 					current_fun['desc'] = context
+					if context == '' and not suppress_warning(filename, first_item(current_fun['names'])):
+						print 'WARNING: member function "%s" is not documented' % (name + '::' + first_item(current_fun['names']))
 					funs.append(current_fun)
 			context = ''
 			blanks = 0
@@ -299,6 +310,8 @@ def parse_class(lno, lines, filename):
 				fields[-1]['names'].append(n)
 				fields[-1]['signatures'].append(l)
 			else:
+				if context == '' and not suppress_warning(filename, n):
+					print 'WARNING: field "%s" is not documented' % (name + '::' + n)
 				fields.append({'signatures': [l], 'names': [n], 'desc': context})
 			context = ''
 			blanks = 0
@@ -308,6 +321,8 @@ def parse_class(lno, lines, filename):
 			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' % (name + '::' + enum['name'])
 				enums.append(enum)
 			context = ''
 			continue
@@ -510,6 +525,7 @@ for filename in files:
 					current_class, lno = parse_class(lno -1, lines, filename)
 					if current_class != None and is_visible(context):
 						current_class['desc'] = context
+						if context == '': print 'WARNING: class "%s" is not documented' % (current_class['name'])
 						classes.append(current_class)
 				context = ''
 				blanks += 1
@@ -523,6 +539,7 @@ for filename in files:
 						functions[-1]['names'].update(current_fun['names'])
 					else:
 						current_fun['desc'] = context
+						if context == '': print 'WARNING: function "%s" is not documented' % (first_item(current_fun['names']))
 						functions.append(current_fun)
 					blanks = 0
 				context = ''
@@ -538,6 +555,7 @@ for filename in files:
 			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' % (current_enum['name'])
 				enums.append(current_enum)
 			context = ''
 			blanks += 1

include/libtorrent/add_torrent_params.hpp

@@ -327,6 +327,12 @@ namespace libtorrent
 		int download_limit;
 
 #ifndef TORRENT_DISABLE_EXTENSIONS
+		// torrent extension construction functions can be added to this
+		// vector to have them be added immediately when the torrent is
+		// constructed. This may be desired over the torrent_handle::add_extension()
+		// in order to avoid race conditions. For instance it may be important
+		// to have the plugin catch events that happen very early on after
+		// the torrent is created.
 		std::vector<boost::function<boost::shared_ptr<torrent_plugin>(torrent*, void*)> > extensions;
 #endif
 	};

include/libtorrent/alert.hpp

@@ -96,6 +96,7 @@ namespace libtorrent {
 		enum severity_t { debug, info, warning, critical, fatal, none };
 #endif
 
+		// these are bits for the alert_mask used by the session. See set_alert_mask().
 		enum category_t
 		{
 			// Enables alerts that report an error. This includes:

include/libtorrent/create_torrent.hpp

@@ -172,6 +172,7 @@ namespace libtorrent
 			, int pad_file_limit = -1, int flags = optimize, int alignment = 0x4000);
 		create_torrent(torrent_info const& ti);
 
+		// internal
 		~create_torrent();
 
 		// This function will generate the .torrent file as a bencode tree. In order to
@@ -199,6 +200,8 @@ namespace libtorrent
 		// any files to the ``file_storage``, torrent generation will fail.
 		entry generate() const;
 
+		// returns an immutable reference to the file_storage used to create
+		// the torrent from.
 		file_storage const& files() const { return m_files; }
 
 		// Sets the comment for the torrent. The string ``str`` should be utf-8 encoded.

include/libtorrent/lazy_entry.hpp

@@ -95,11 +95,21 @@ namespace libtorrent
 		, lazy_entry& ret, int depth_limit = 1000, int item_limit = 1000000) TORRENT_DEPRECATED;
 #endif
 
+	// this is a string that is not NULL-terminated. Instead it
+	// comes with a length, specified in bytes. This is particularly
+	// useful when parsing bencoded structures, because strings are
+	// not NULL-terminated internally, and requiring NULL termination
+	// would require copying the string.
+	//
+	// see lazy_entry::string_pstr().
 	struct TORRENT_EXPORT pascal_string
 	{
 		pascal_string(char const* p, int l): len(l), ptr(p) {}
 		int len;
 		char const* ptr;
+
+		// lexicographical comparison of strings. Order is consisten
+		// with memcmp.
 		bool operator<(pascal_string const& rhs) const
 		{
 			return std::memcmp(ptr, rhs.ptr, (std::min)(len, rhs.len)) < 0
@@ -109,8 +119,19 @@ namespace libtorrent
 
 	struct lazy_dict_entry;
 
+	// this object represent a node in a bencoded structure. It is a variant
+	// type whose concrete type is one of:
+	//
+	// 1. dictionary (maps strings -> lazy_entry)
+	// 2. list (sequence of lazy_entry, i.e. heterogenous)
+	// 3. integer
+	// 4. string
+	//
+	// There is also a ``none`` type, which is used for uninitialized
+	// lazy_entries.
 	struct TORRENT_EXPORT lazy_entry
 	{
+		// The different types a lazy_entry can have
 		enum entry_type_t
 		{
 			none_t, dict_t, list_t, string_t, int_t
@@ -119,6 +140,9 @@ namespace libtorrent
 		lazy_entry() : m_begin(0), m_len(0), m_size(0), m_capacity(0), m_type(none_t)
 		{ m_data.start = 0; }
 
+		// tells you which specific type this lazy entry has.
+		// See entry_type_t. The type determines which subset of
+		// member functions are valid to use.
 		entry_type_t type() const { return (entry_type_t)m_type; }
 
 		// start points to the first decimal digit
@@ -133,14 +157,15 @@ namespace libtorrent
 			m_len = length + 2; // include 'e'
 		}
 
+		// if this is an integer, return the integer value
 		size_type int_value() const;
 
-		// string functions
-		// ================
-
+		// internal
 		void construct_string(char const* start, int length);
 
 		// the string is not null-terminated!
+		// use string_length() to determine how many bytes
+		// are part of the string.
 		char const* string_ptr() const
 		{
 			TORRENT_ASSERT(m_type == string_t);
@@ -156,24 +181,28 @@ namespace libtorrent
 			return m_data.start;
 		}
 
+		// if this is a string, returns a pascal_string
+		// representing the string value.
 		pascal_string string_pstr() const
 		{
 			TORRENT_ASSERT(m_type == string_t);
 			return pascal_string(m_data.start, m_size);
 		}
 
+		// if this is a string, returns the string as a std::string.
+		// (which requires a copy)
 		std::string string_value() const
 		{
 			TORRENT_ASSERT(m_type == string_t);
 			return std::string(m_data.start, m_size);
 		}
 
+		// if the lazy_entry is a string, returns the
+		// length of the string, in bytes.
 		int string_length() const
 		{ return m_size; }
 
-		// dictionary functions
-		// ====================
-
+		// internal
 		void construct_dict(char const* begin)
 		{
 			TORRENT_ASSERT(m_type == none_t);
@@ -183,31 +212,45 @@ namespace libtorrent
 			m_begin = begin;
 		}
 
+		// internal
 		lazy_entry* dict_append(char const* name);
+		// internal
 		void pop();
+
+		// if this is a dictionary, look for a key ``name``, and return
+		// a pointer to its value, or NULL if there is none.
 		lazy_entry* dict_find(char const* name);
 		lazy_entry const* dict_find(char const* name) const
 		{ return const_cast<lazy_entry*>(this)->dict_find(name); }
+		lazy_entry const* dict_find_string(char const* name) const;
 
+		// if this is a dictionary, look for a key ``name`` whose value
+		// is a string. If such key exist, return a pointer to
+		// its value, otherwise NULL.
 		std::string dict_find_string_value(char const* name) const;
 		pascal_string dict_find_pstr(char const* name) const;
+
+		// if this is a dictionary, look for a key ``name`` whose value
+		// is an int. If such key exist, return a pointer to its value,
+		// otherwise NULL.
 		size_type dict_find_int_value(char const* name, size_type default_val = 0) const;
-		lazy_entry const* dict_find_dict(char const* name) const;
-		lazy_entry const* dict_find_list(char const* name) const;
-		lazy_entry const* dict_find_string(char const* name) const;
 		lazy_entry const* dict_find_int(char const* name) const;
 
+		lazy_entry const* dict_find_dict(char const* name) const;
+		lazy_entry const* dict_find_list(char const* name) const;
+
+		// if this is a dictionary, return the key value pair at
+		// 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
 		int dict_size() const
 		{
 			TORRENT_ASSERT(m_type == dict_t);
 			return m_size;
 		}
 
-		// list functions
-		// ==============
-
+		// internal
 		void construct_list(char const* begin)
 		{
 			TORRENT_ASSERT(m_type == none_t);
@@ -217,7 +260,10 @@ namespace libtorrent
 			m_begin = begin;
 		}
 
+		// internal
 		lazy_entry* list_append();
+
+		// if this is a list, return the item at index ``i``.
 		lazy_entry* list_at(int i)
 		{
 			TORRENT_ASSERT(m_type == list_t);
@@ -231,19 +277,22 @@ namespace libtorrent
 		pascal_string list_pstr_at(int i) const;
 		size_type list_int_value_at(int i, size_type default_val = 0) const;
 
+		// if this is a list, return the number of items in it.
 		int list_size() const
 		{
 			TORRENT_ASSERT(m_type == list_t);
 			return int(m_size);
 		}
 
-		// end points one byte passed last byte
+		// end points one byte passed last byte in the source
+		// buffer backing the bencoded structure.
 		void set_end(char const* end)
 		{
 			TORRENT_ASSERT(end > m_begin);
 			m_len = end - m_begin;
 		}
 		
+		// internal
 		void clear();
 
 		// releases ownership of any memory allocated
@@ -255,6 +304,7 @@ namespace libtorrent
 			m_type = none_t;
 		}
 
+		// internal
 		~lazy_entry()
 		{ clear(); }
 
@@ -262,6 +312,7 @@ namespace libtorrent
 		// this entry has its bencoded data
 		std::pair<char const*, int> data_section() const;
 
+		// swap values of ``this`` and ``e``.
 		void swap(lazy_entry& e)
 		{
 			using std::swap;

include/libtorrent/rss.hpp

@@ -75,6 +75,7 @@ namespace libtorrent
 		sha1_hash info_hash;
 	};
 
+	// given a feed_item ``f``, add the torrent it refers to to session ``s``.
 #ifndef BOOST_NO_EXCEPTIONS
 	torrent_handle TORRENT_EXPORT add_feed_item(session& s, feed_item const& fi
 		, add_torrent_params const& p);

include/libtorrent/storage.hpp

@@ -367,6 +367,7 @@ namespace libtorrent
 		mutable error_code m_error;
 		mutable std::string m_error_file;
 
+		// hidden
 		virtual ~storage_interface() {}
 
 		disk_buffer_pool* m_disk_pool;

include/libtorrent/storage_defs.hpp

@@ -43,6 +43,7 @@ namespace libtorrent
 	class file_storage;
 	struct file_pool;
 
+	// types of storage allocation used for add_torrent_params::storage_mode.
 	enum storage_mode_t
 	{
 		// All pieces will be written to their final position, all files will be

include/libtorrent/thread.hpp

@@ -57,6 +57,8 @@ namespace libtorrent
 	typedef boost::asio::detail::mutex mutex;
 	typedef boost::asio::detail::event event;
 
+	// pauses the calling thread at least for the specified
+	// number of milliseconds
 	TORRENT_EXPORT void sleep(int milliseconds);
 
 	struct TORRENT_EXTRA_EXPORT condition_variable

include/libtorrent/time.hpp

@@ -63,20 +63,32 @@ namespace libtorrent
 	TORRENT_EXTRA_EXPORT char const* time_now_string();
 	std::string log_time();
 
+	// returns the current time, as represented by ptime. The
+	// resolution of this timer is about 100 ms.
 	TORRENT_EXPORT ptime const& time_now();
+
+	// returns the current time as represented by ptime. This is
+	// more expensive than time_now(), but provides as high resolution
+	// as the operating system can provide.
 	TORRENT_EXPORT ptime time_now_hires();
 
+	// the earliest and latest possible time points
+	// representable by ptime.
 	TORRENT_EXPORT ptime min_time();
 	TORRENT_EXPORT ptime max_time();
 
 #if defined TORRENT_USE_BOOST_DATE_TIME || defined TORRENT_USE_QUERY_PERFORMANCE_TIMER
 
+	// returns a time_duration representing the specified number of seconds, milliseconds
+	// microseconds, minutes and hours.
 	TORRENT_EXPORT time_duration seconds(int s);
 	TORRENT_EXPORT time_duration milliseconds(int s);
 	TORRENT_EXPORT time_duration microsec(int s);
 	TORRENT_EXPORT time_duration minutes(int s);
 	TORRENT_EXPORT time_duration hours(int s);
 
+	// returns the number of seconds, milliseconds and microseconds
+	// a time_duration represents.
 	TORRENT_EXPORT int total_seconds(time_duration td);
 	TORRENT_EXPORT int total_milliseconds(time_duration td);
 	TORRENT_EXPORT boost::int64_t total_microseconds(time_duration td);

include/libtorrent/torrent_handle.hpp

@@ -199,7 +199,7 @@ namespace libtorrent
 	// 	expensive if done from within a GUI thread that needs to stay responsive.
 	// 	Try to avoid quering for information you don't need, and try to do it
 	// 	in as few calls as possible. You can get most of the interesting information
-	// 	about a torrent from the ``torrent_handle::status()`` call.
+	// 	about a torrent from the torrent_handle::status() call.
 	// 
 	// The default constructor will initialize the handle to an invalid state. Which
 	// means you cannot perform any operation on it, unless you first assign it a
@@ -435,7 +435,7 @@ namespace libtorrent
 		// that refers to that torrent will become invalid.
 		bool is_valid() const;
 
-		// flags for pause()
+		// flags for torrent_session::pause()
 		enum pause_flags_t { graceful_pause = 1 };
 
 		// ``pause()``, and ``resume()`` will disconnect all peers and reconnect all peers respectively.
@@ -993,12 +993,12 @@ namespace libtorrent
 		// ``info_hash()`` returns the info-hash for the torrent.
 		sha1_hash info_hash() const;
 
+		// comparison operators. The order of the torrents is unspecified
+		// but stable.
 		bool operator==(const torrent_handle& h) const
 		{ return m_torrent.lock() == h.m_torrent.lock(); }
-
 		bool operator!=(const torrent_handle& h) const
 		{ return m_torrent.lock() != h.m_torrent.lock(); }
-
 		bool operator<(const torrent_handle& h) const
 		{ return m_torrent.lock() < h.m_torrent.lock(); }
 
@@ -1023,8 +1023,10 @@ namespace libtorrent
 
 	};
 
+	// holds a snapshot of the status of a torrent, as queried by torrent_handle::status().
 	struct TORRENT_EXPORT torrent_status
 	{
+		// hidden
 		torrent_status();
 		~torrent_status();
 
@@ -1034,6 +1036,7 @@ namespace libtorrent
 		// a handle to the torrent whose status the object represents.
 		torrent_handle handle;
 
+		// the different overall states a torrent can be in
 		enum state_t
 		{
 			// The torrent is in the queue for being checked. But there
@@ -1076,6 +1079,7 @@ namespace libtorrent
 			checking_resume_data
 		};
 		
+		// the main state the torrent is in. See torrent_status::state_t.
 		state_t state;
 
 		// set to true if the torrent is paused and false otherwise. It's only true