documetation fixes and polish

docs/gen_reference_doc.py

@@ -62,9 +62,9 @@ anon_index = 0
 
 category_mapping = {
 	'ed25519.hpp': 'ed25519',
-	'session.hpp': 'Session',
+	'session.hpp': 'Core',
-	'add_torrent_params.hpp': 'Session',
+	'add_torrent_params.hpp': 'Core',
-	'session_status.hpp': 'Session',
+	'session_status.hpp': 'Core',
 	'error_code.hpp': 'Error Codes',
 	'file.hpp': 'File',
 	'storage.hpp': 'Custom Storage',
@@ -86,9 +86,7 @@ category_mapping = {
 	'bdecode.hpp': 'Bdecoding',
 	'entry.hpp': 'Bencoding',
 	'time.hpp': 'Time',
-	'escape_string.hpp': 'String',
+	'escape_string.hpp': 'Utility',
-	'string_util.hpp': 'String',
-	'utf8.hpp': 'String',
 	'enum_net.hpp': 'Network',
 	'broadcast_socket.hpp': 'Network',
 	'socket.hpp': 'Network',
@@ -96,18 +94,21 @@ category_mapping = {
 	'rss.hpp': 'RSS',
 	'bitfield.hpp': 'Utility',
 	'sha1_hash.hpp': 'Utility',
+	'hasher.hpp': 'Utility',
 	'identify_client.hpp': 'Utility',
 	'thread.hpp': 'Utility',
 	'ip_filter.hpp': 'Filter',
 	'session_settings.hpp': 'Settings',
 	'settings_pack.hpp': 'Settings',
 	'operations.hpp': 'Alerts',
+	'disk_buffer_holder.hpp': 'Custom Storage',
+	'alert_dispatcher.hpp': 'Alerts',
 }
 
 category_fun_mapping = {
 	'min_memory_usage()': 'Settings',
 	'high_performance_seed()': 'Settings',
-	'cache_status': 'Session',
+	'cache_status': 'Core',
 }
 
 def categorize_symbol(name, filename):
@@ -841,14 +842,15 @@ def dump_link_targets(indent = ''):
 	return ret
 
 def heading(string, c, indent = ''):
+	string = string.strip()
 	return '\n' + indent + string + '\n' + indent + (c * len(string)) + '\n'
 
-def render_enums(out, enums, print_declared_reference):
+def render_enums(out, enums, print_declared_reference, header_level):
 	for e in enums:
 		print >>out, '.. raw:: html\n'
 		print >>out, '\t<a name="%s"></a>' % e['name']
 		print >>out, ''
-		print >>out, heading('enum %s' % e['name'], '.')
+		print >>out, heading('enum %s' % e['name'], header_level)
 
 		print_declared_in(out, e)
 
@@ -890,7 +892,6 @@ sections = \
 	'Create Torrents': 1,
 
 	'ed25519': 2,
-	'String': 2,
 	'Utility': 2,
 	'Storage': 2,
 	'Custom Storage': 2,
@@ -1022,7 +1023,7 @@ for cat in categories:
 	
 			print >>out, dump_link_targets()
 
-		render_enums(out, c['enums'], False)
+		render_enums(out, c['enums'], False, '.')
 
 		for f in c['fields']:
 			if f['desc'] == '': continue
@@ -1049,7 +1050,7 @@ for cat in categories:
 		print >>out, ''
 		for n in f['names']:
 			h += '%s ' % n
-		print >>out, heading(h, '.')
+		print >>out, heading(h, '-')
 		print_declared_in(out, f)
 
 		block = '.. parsed-literal::\n\n'
@@ -1061,7 +1062,7 @@ for cat in categories:
 
 		print >>out, dump_link_targets()
 	
-	render_enums(out, enums, True)
+	render_enums(out, enums, True, '-')
 
 	print >>out, dump_link_targets()
 

docs/makefile

@@ -4,9 +4,7 @@ WEB_PATH = ~/Documents/rasterbar/web/products/libtorrent
 
 REFERENCE_TARGETS = \
 	reference \
-	reference-Session \
 	reference-Core \
-	reference-String \
 	reference-Plugins \
 	reference-Create_Torrents \
 	reference-Error_Codes \

docs/manual.rst

@@ -687,7 +687,6 @@ disk cache, by requesting all blocks in a single piece, from the same peer.
 This threshold is controlled by the settings_pack::whole_pieces_threshold
 setting.
 
-*TODO: piece affinity by speed category*
 *TODO: piece priorities*
 
 predictive piece announce

docs/rst.css

@@ -121,9 +121,9 @@ p.admonition-title {
     border-bottom: solid 1px #D1DFD5
 }
 
-h1 { font-size: 180%; }
+h1 { font-size: 200%; }
 h2 { font-size: 130%; }
-h3 { font-size: 100%; }
+h3 { font-size: 100%; font-style: italic; }
 
 h1.title { text-align: center; }
 

docs/stats_counters.rst

@@ -28,6 +28,8 @@ disconnected initiated by this client (``disconnected_peers``).
 
 .. _peer.connaborted_peers:
 
+.. _peer.notconnected_peers:
+
 .. _peer.perm_peers:
 
 .. _peer.buffer_peers:
@@ -50,6 +52,7 @@ disconnected initiated by this client (``disconnected_peers``).
 	<a name="peer.connreset_peers"></a>
 	<a name="peer.connrefused_peers"></a>
 	<a name="peer.connaborted_peers"></a>
+	<a name="peer.notconnected_peers"></a>
 	<a name="peer.perm_peers"></a>
 	<a name="peer.buffer_peers"></a>
 	<a name="peer.unreachable_peers"></a>
@@ -59,33 +62,35 @@ disconnected initiated by this client (``disconnected_peers``).
 	<a name="peer.invalid_arg_peers"></a>
 	<a name="peer.aborted_peers"></a>
 
-+------------------------+---------+
++-------------------------+---------+
-| name                   | type    |
+| name                    | type    |
-+========================+=========+
++=========================+=========+
-| peer.eof_peers         | counter |
+| peer.eof_peers          | counter |
-+------------------------+---------+
++-------------------------+---------+
-| peer.connreset_peers   | counter |
+| peer.connreset_peers    | counter |
-+------------------------+---------+
++-------------------------+---------+
-| peer.connrefused_peers | counter |
+| peer.connrefused_peers  | counter |
-+------------------------+---------+
++-------------------------+---------+
-| peer.connaborted_peers | counter |
+| peer.connaborted_peers  | counter |
-+------------------------+---------+
++-------------------------+---------+
-| peer.perm_peers        | counter |
+| peer.notconnected_peers | counter |
-+------------------------+---------+
++-------------------------+---------+
-| peer.buffer_peers      | counter |
+| peer.perm_peers         | counter |
-+------------------------+---------+
++-------------------------+---------+
-| peer.unreachable_peers | counter |
+| peer.buffer_peers       | counter |
-+------------------------+---------+
++-------------------------+---------+
-| peer.broken_pipe_peers | counter |
+| peer.unreachable_peers  | counter |
-+------------------------+---------+
++-------------------------+---------+
-| peer.addrinuse_peers   | counter |
+| peer.broken_pipe_peers  | counter |
-+------------------------+---------+
++-------------------------+---------+
-| peer.no_access_peers   | counter |
+| peer.addrinuse_peers    | counter |
-+------------------------+---------+
++-------------------------+---------+
-| peer.invalid_arg_peers | counter |
+| peer.no_access_peers    | counter |
-+------------------------+---------+
++-------------------------+---------+
-| peer.aborted_peers     | counter |
+| peer.invalid_arg_peers  | counter |
-+------------------------+---------+
++-------------------------+---------+
+| peer.aborted_peers      | counter |
++-------------------------+---------+
 
 
 these counters break down the peer errors into more specific

docs/style.css

@@ -12,8 +12,7 @@
 body, table { font: 0.9em Verdana, sans-serif;}
 
 h1, h2, h3 {
-    font: 1.5em Georgia "Times New Roman", serif;
+    font-family: Georgia "Times New Roman", serif;
-/*    letter-spacing: 1px; */
     padding-bottom: 0.5em;
     font-weight: bold;
 }

include/libtorrent/add_torrent_params.hpp

@@ -318,7 +318,8 @@ namespace libtorrent
 		storage_constructor_type storage;
 
 		// The ``userdata`` parameter is optional and will be passed on to the
-		// extension constructor functions, if any (see `add_extension()`_).
+		// extension constructor functions, if any
+		// (see torrent_handle::add_extension()).
 		void* userdata;
 
 		// can be set to control the initial file priorities when adding a

include/libtorrent/bdecode.hpp

@@ -287,12 +287,16 @@ struct TORRENT_EXPORT bdecode_node
 		, boost::int64_t default_val = 0);
 	int list_size() const;
 
-	// functions with the ``dict_`` prefix operates on dictionaries. Theu are
+	// Functions with the ``dict_`` prefix operates on dictionaries. They are
 	// only valid if ``type()`` == ``dict_t``. In case a key you're looking up
 	// contains a 0 byte, you cannot use the null-terminated string overloads,
-	// but have to use ``std::string`` instead. ``dict_find_list`` will return
+	// but have to use ``std::string`` instead. ``dict_find_list`` will return a
-	// a valid ``bdecode_node`` if the key is found _and_ it is a list. Otherwise
+	// valid ``bdecode_node`` if the key is found _and_ it is a list. Otherwise
 	// it will return a default-constructed bdecode_node.
+	// 
+	// Functions with the ``_value`` suffix return the value of the node
+	// directly, rather than the nodes. In case the node is not found, or it has
+	// a different type, a default value is returned (which can be specified).
 	bdecode_node dict_find(std::string key) const;
 	bdecode_node dict_find(char const* key) const;
 	std::pair<std::string, bdecode_node> dict_at(int i) const;
@@ -312,7 +316,7 @@ struct TORRENT_EXPORT bdecode_node
 	boost::int64_t int_value() const;
 
 	// these functions are only valid if ``type()`` == ``string_t``. They return
-	// the string values. Note that ``string_ptr()`` is _not_ null-terminated.
+	// the string values. Note that ``string_ptr()`` is *not* null-terminated.
 	// ``string_length()`` returns the number of bytes in the string.
 	std::string string_value() const;
 	char const* string_ptr() const;
@@ -332,9 +336,9 @@ struct TORRENT_EXPORT bdecode_node
 	// passing it in to bdecode().
 	void reserve(int tokens);
 
-	// this buffer MUST be identical to the one originally parsed.
+	// this buffer *MUST* be identical to the one originally parsed. This
-	// This operation is only defined on owning root nodes, i.e. the one
+	// operation is only defined on owning root nodes, i.e. the one passed in to
-	// passed in to decode().
+	// decode().
 	void switch_underlying_buffer(char const* buf);
 
 private:
@@ -375,12 +379,12 @@ TORRENT_EXPORT std::string print_entry(bdecode_node const& e
 	, bool single_line = false, int indent = 0);
 
 // This function decodes/parses bdecoded data (for example a .torrent file).
-// The data structure is returned in the ``ret`` argument.
+// The data structure is returned in the ``ret`` argument. the buffer to parse
-// the buffer to parse is specified by the ``start`` of the buffer as well as
+// is specified by the ``start`` of the buffer as well as the ``end``, i.e. one
-// the ``end``, i.e. one byte past the end. If the buffer fails to parse, the
+// byte past the end. If the buffer fails to parse, the function returns a
-// function returns a non-zero value and fills in ``ec`` with the error code.
+// non-zero value and fills in ``ec`` with the error code. The optional
-// The optional argument ``error_pos``, if set to non-null, will be set to the byte
+// argument ``error_pos``, if set to non-null, will be set to the byte offset
-// offset into the buffer where the parse failure occurred.
+// into the buffer where the parse failure occurred.
 // 
 // ``depth_limit`` specifies the max number of nested lists or dictionaries are
 // allowed in the data structure. (This affects the stack usage of the
@@ -391,9 +395,9 @@ TORRENT_EXPORT std::string print_entry(bdecode_node const& e
 // 
 // The resulting ``bdecode_node`` is an *owning* node. That means it will
 // be holding the whole parsed tree. When iterating lists and dictionaries,
-// those ``bdecode_node``s will simply have references to the root or owning
+// those ``bdecode_node`` objects will simply have references to the root or
-// ``bdecode_node``. If the root node is destructed, all other nodes that
+// owning ``bdecode_node``. If the root node is destructed, all other nodes
-// refer to anything in that tree become invalid.
+// that refer to anything in that tree become invalid.
 // 
 // However, the underlying buffer passed in to this function (``start``, ``end``)
 // must also remain valid while the bdecoded tree is used. The parsed tree

include/libtorrent/bencode.hpp

@@ -38,44 +38,38 @@ POSSIBILITY OF SUCH DAMAGE.
 
 // OVERVIEW
 // 
-// Bencoding is a common representation in bittorrent used for
+// Bencoding is a common representation in bittorrent used for for dictionary,
-// for dictionary, list, int and string hierarchies. It's used
+// list, int and string hierarchies. It's used to encode .torrent files and
-// to encode .torrent files and some messages in the network
+// some messages in the network protocol. libtorrent also uses it to store
-// protocol. libtorrent also uses it to store settings, resume
+// settings, resume data and other state between sessions.
-// data and other state between sessions.
 //
-// Strings in bencoded structures are not necessarily representing
+// Strings in bencoded structures are not necessarily representing text.
-// text. Strings are raw byte buffers of a certain length. If a
+// Strings are raw byte buffers of a certain length. If a string is meant to be
-// string is meant to be interpreted as text, it is required to
+// interpreted as text, it is required to be UTF-8 encoded. See `BEP 3`_.
-// be UTF-8 encoded. See `BEP 3`_.
 //
 // There are two mechanims to *decode* bencoded buffers in libtorrent.
 //
 // The most flexible one is `bdecode() bencode()`_, which returns a structure
-// represented by entry. When a buffer is decoded with this function,
+// represented by entry. Oncea buffer has been decoded with this function, it
-// it can be discarded. The entry does not contain any references back
+// can be discarded. The entry does not contain any references back to it. This
-// to it. This means that bdecode() actually copies all the data out
+// means that bdecode() copies all the data out of the buffer and into its own
-// of the buffer and into its own hierarchy. This makes this
+// hierarchy. This makes this function expensive, which might matter if you're
-// function potentially expensive, if you're parsing large amounts
+// parsing large amounts of data.
-// of data.
 //
 // Another consideration is that `bdecode() bencode()`_ is a recursive parser.
-// For this reason, in order to avoid DoS attacks by triggering
+// For this reason, in order to avoid DoS attacks by triggering a stack
-// a stack overflow, there is a recursion limit. This limit is
+// overflow, there is a recursion limit. This limit is a sanity check to make
-// a sanity check to make sure it doesn't run the risk of
+// sure it doesn't run the risk of busting the stack.
-// busting the stack.
 //
-// The second mechanism is bdecode(), which returns a
+// The second mechanism is the decode function for bdecode_node. This function
-// bencoded structure represented by bdecode_node. This function
+// builds a tree that points back into the original buffer. The returned
-// builds a tree that points back into the original buffer.
+// bdecode_node will not be valid once the buffer it was parsed out of is
-// The returned bdecode_node will not be valid once the buffer
+// discarded.
-// it was parsed out of is discarded.
 //
-// Not only is this function more efficient because of less
+// Not only is this function more efficient because of less memory allocation
-// memory allocation and data copy, the parser is also not
+// and data copy, the parser is also not recursive, which means it probably
-// recursive, which means it probably performs a little bit
+// performs a little bit better and can have a higher recursion limit on the
-// better and can have a higher recursion limit on the structures
+// structures it's parsing.
-// it's parsing.
 
 #include <stdlib.h>
 #include <string>

include/libtorrent/block_cache.hpp

@@ -321,6 +321,7 @@ namespace libtorrent
 #endif
 	};
 
+	// internal
 	inline std::size_t hash_value(cached_piece_entry const& p)
 	{
 		return std::size_t(p.storage.get()) + std::size_t(p.piece);

include/libtorrent/escape_string.hpp

@@ -80,14 +80,13 @@ namespace libtorrent
 
 	TORRENT_EXTRA_EXPORT bool is_hex(char const *in, int len);
 
-	// converts (binary) the string ``s`` to hexadecimal representation and
+	// The overload taking a ``std::string`` converts (binary) the string ``s``
-	// returns it.
+	// to hexadecimal representation and returns it.
+	// The overload taking a ``char const*`` and a length 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 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

include/libtorrent/peer_info.hpp

@@ -216,7 +216,7 @@ namespace libtorrent
 		};
 
 		// a combination of flags describing from which sources this peer
-		// was received.
+		// was received. See peer_source_flags.
 		boost::uint32_t source;
 
 		// the current upload and download speed we have to and from this peer
@@ -305,7 +305,7 @@ namespace libtorrent
 		// the kind of connection this is. Used for the connection_type field.
 		enum connection_type_t
 		{
-			// Regular bittorrent connection over TCP
+			// Regular bittorrent connection
 			standard_bittorrent = 0,
 
 			// HTTP connection using the `BEP 19`_ protocol

include/libtorrent/sha1_hash.hpp

@@ -69,6 +69,7 @@ namespace libtorrent
 	{
 		enum { number_size = 5 };
 	public:
+		// internal
 		// the number of bytes of the number
 		static const int size = number_size * sizeof(boost::uint32_t);
 

include/libtorrent/string_util.hpp

@@ -40,8 +40,11 @@ POSSIBILITY OF SUCH DAMAGE.
 namespace libtorrent
 {
 	TORRENT_EXTRA_EXPORT bool is_alpha(char c);
-	// this is used by bdecode_recursive's header file
+
-	TORRENT_EXPORT bool is_digit(char c);
+	// internal
+	inline bool is_digit(char c)
+	{ return c >= '0' && c <= '9'; }
+
 	TORRENT_EXTRA_EXPORT bool is_print(char c);
 	TORRENT_EXTRA_EXPORT bool is_space(char c);
 	TORRENT_EXTRA_EXPORT char to_lower(char c);

include/libtorrent/utf8.hpp

@@ -45,6 +45,7 @@ POSSIBILITY OF SUCH DAMAGE.
 namespace libtorrent
 {
 
+	// internal
 	// results from UTF-8 conversion functions utf8_wchar and
 	// wchar_utf8
 	enum utf8_conv_result_t

src/entry.cpp

@@ -131,15 +131,15 @@ namespace libtorrent
 #ifndef BOOST_NO_EXCEPTIONS
 	const entry& entry::operator[](char const* key) const
 	{
-		dictionary_type::const_iterator i = dict().find(key);
+		return (*this)[std::string(key)];
-		if (i == dict().end()) throw type_error(
-			(std::string("key not found: ") + key).c_str());
-		return i->second;
 	}
 
 	const entry& entry::operator[](std::string const& key) const
 	{
-		return (*this)[key.c_str()];
+		dictionary_type::const_iterator i = dict().find(key);
+		if (i == dict().end()) throw type_error(
+			(std::string("key not found: ") + key).c_str());
+		return i->second;
 	}
 #endif
 

src/string_util.cpp

@@ -45,11 +45,6 @@ namespace libtorrent
 		return (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z');
 	}
 
-	bool is_digit(char c)
-	{
-		return c >= '0' && c <= '9';
-	}
-
 	bool is_print(char c)
 	{
 		return c >= 32 && c < 127;