From fad1c42970d59e9cfde49f31e2b18bdb810ee421 Mon Sep 17 00:00:00 2001 From: Arvid Norberg Date: Sat, 14 Mar 2015 21:55:26 +0000 Subject: [PATCH] documetation fixes and polish --- docs/gen_reference_doc.py | 27 ++++++----- docs/makefile | 2 - docs/manual.rst | 1 - docs/rst.css | 4 +- docs/stats_counters.rst | 59 ++++++++++++----------- docs/style.css | 3 +- include/libtorrent/add_torrent_params.hpp | 3 +- include/libtorrent/bdecode.hpp | 36 ++++++++------ include/libtorrent/bencode.hpp | 52 +++++++++----------- include/libtorrent/block_cache.hpp | 1 + include/libtorrent/escape_string.hpp | 13 +++-- include/libtorrent/peer_info.hpp | 4 +- include/libtorrent/sha1_hash.hpp | 1 + include/libtorrent/string_util.hpp | 7 ++- include/libtorrent/utf8.hpp | 1 + src/entry.cpp | 10 ++-- src/string_util.cpp | 5 -- 17 files changed, 115 insertions(+), 114 deletions(-) diff --git a/docs/gen_reference_doc.py b/docs/gen_reference_doc.py index 8451c541c..89c4cfe5d 100644 --- a/docs/gen_reference_doc.py +++ b/docs/gen_reference_doc.py @@ -62,9 +62,9 @@ anon_index = 0 category_mapping = { 'ed25519.hpp': 'ed25519', - 'session.hpp': 'Session', - 'add_torrent_params.hpp': 'Session', - 'session_status.hpp': 'Session', + 'session.hpp': 'Core', + 'add_torrent_params.hpp': 'Core', + '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', - 'string_util.hpp': 'String', - 'utf8.hpp': 'String', + 'escape_string.hpp': 'Utility', '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' % 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() diff --git a/docs/makefile b/docs/makefile index d39b4809b..84f46bb93 100644 --- a/docs/makefile +++ b/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 \ diff --git a/docs/manual.rst b/docs/manual.rst index 7a25d7a3e..08e543a3f 100644 --- a/docs/manual.rst +++ b/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 diff --git a/docs/rst.css b/docs/rst.css index 42c112ba6..fb911fd7e 100644 --- a/docs/rst.css +++ b/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; } diff --git a/docs/stats_counters.rst b/docs/stats_counters.rst index e9eed43f9..b6c6f864e 100644 --- a/docs/stats_counters.rst +++ b/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``). + @@ -59,33 +62,35 @@ disconnected initiated by this client (``disconnected_peers``). -+------------------------+---------+ -| name | type | -+========================+=========+ -| peer.eof_peers | counter | -+------------------------+---------+ -| peer.connreset_peers | counter | -+------------------------+---------+ -| peer.connrefused_peers | counter | -+------------------------+---------+ -| peer.connaborted_peers | counter | -+------------------------+---------+ -| peer.perm_peers | counter | -+------------------------+---------+ -| peer.buffer_peers | counter | -+------------------------+---------+ -| peer.unreachable_peers | counter | -+------------------------+---------+ -| peer.broken_pipe_peers | counter | -+------------------------+---------+ -| peer.addrinuse_peers | counter | -+------------------------+---------+ -| peer.no_access_peers | counter | -+------------------------+---------+ -| peer.invalid_arg_peers | counter | -+------------------------+---------+ -| peer.aborted_peers | counter | -+------------------------+---------+ ++-------------------------+---------+ +| name | type | ++=========================+=========+ +| peer.eof_peers | counter | ++-------------------------+---------+ +| peer.connreset_peers | counter | ++-------------------------+---------+ +| peer.connrefused_peers | counter | ++-------------------------+---------+ +| peer.connaborted_peers | counter | ++-------------------------+---------+ +| peer.notconnected_peers | counter | ++-------------------------+---------+ +| peer.perm_peers | counter | ++-------------------------+---------+ +| peer.buffer_peers | counter | ++-------------------------+---------+ +| peer.unreachable_peers | counter | ++-------------------------+---------+ +| peer.broken_pipe_peers | counter | ++-------------------------+---------+ +| peer.addrinuse_peers | counter | ++-------------------------+---------+ +| peer.no_access_peers | counter | ++-------------------------+---------+ +| peer.invalid_arg_peers | counter | ++-------------------------+---------+ +| peer.aborted_peers | counter | ++-------------------------+---------+ these counters break down the peer errors into more specific diff --git a/docs/style.css b/docs/style.css index b6e6e04b6..4e50f5399 100644 --- a/docs/style.css +++ b/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; -/* letter-spacing: 1px; */ + font-family: Georgia "Times New Roman", serif; padding-bottom: 0.5em; font-weight: bold; } diff --git a/include/libtorrent/add_torrent_params.hpp b/include/libtorrent/add_torrent_params.hpp index 0c276a108..08cb7f8e0 100644 --- a/include/libtorrent/add_torrent_params.hpp +++ b/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 diff --git a/include/libtorrent/bdecode.hpp b/include/libtorrent/bdecode.hpp index f05269556..27bc90a0e 100644 --- a/include/libtorrent/bdecode.hpp +++ b/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 - // a valid ``bdecode_node`` if the key is found _and_ it is a list. Otherwise + // but have to use ``std::string`` instead. ``dict_find_list`` will return a + // 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 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 operation is only defined on owning root nodes, i.e. the one - // passed in to decode(). + // this buffer *MUST* be identical to the one originally parsed. This + // operation is only defined on owning root nodes, i.e. the one passed in to + // 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 buffer to parse is specified by the ``start`` of the buffer as well as -// the ``end``, i.e. one byte past the end. If the buffer fails to parse, the -// function returns a non-zero value and fills in ``ec`` with the error code. -// The optional argument ``error_pos``, if set to non-null, will be set to the byte -// offset into the buffer where the parse failure occurred. +// The data structure is returned in the ``ret`` argument. the buffer to parse +// is specified by the ``start`` of the buffer as well as the ``end``, i.e. one +// byte past the end. If the buffer fails to parse, the function returns a +// non-zero value and fills in ``ec`` with the error code. The optional +// argument ``error_pos``, if set to non-null, will be set to the byte offset +// 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 -// ``bdecode_node``. If the root node is destructed, all other nodes that -// refer to anything in that tree become invalid. +// those ``bdecode_node`` objects will simply have references to the root or +// owning ``bdecode_node``. If the root node is destructed, all other nodes +// 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 diff --git a/include/libtorrent/bencode.hpp b/include/libtorrent/bencode.hpp index 16b86414a..e0e0f17c0 100644 --- a/include/libtorrent/bencode.hpp +++ b/include/libtorrent/bencode.hpp @@ -38,44 +38,38 @@ POSSIBILITY OF SUCH DAMAGE. // OVERVIEW // -// Bencoding is a common representation in bittorrent used for -// for dictionary, list, int and string hierarchies. It's used -// to encode .torrent files and some messages in the network -// protocol. libtorrent also uses it to store settings, resume -// data and other state between sessions. +// Bencoding is a common representation in bittorrent used for for dictionary, +// list, int and string hierarchies. It's used to encode .torrent files and +// some messages in the network protocol. libtorrent also uses it to store +// settings, resume data and other state between sessions. // -// Strings in bencoded structures are not necessarily representing -// text. Strings are raw byte buffers of a certain length. If a -// string is meant to be interpreted as text, it is required to -// be UTF-8 encoded. See `BEP 3`_. +// Strings in bencoded structures are not necessarily representing text. +// Strings are raw byte buffers of a certain length. If a string is meant to be +// interpreted as text, it is required to 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, -// it can be discarded. The entry does not contain any references back -// to it. This means that bdecode() actually copies all the data out -// of the buffer and into its own hierarchy. This makes this -// function potentially expensive, if you're parsing large amounts -// of data. +// represented by entry. Oncea buffer has been decoded with this function, it +// can be discarded. The entry does not contain any references back to it. This +// means that bdecode() copies all the data out of the buffer and into its own +// hierarchy. This makes this function expensive, which might matter if you're +// parsing large amounts of data. // // Another consideration is that `bdecode() bencode()`_ is a recursive parser. -// For this reason, in order to avoid DoS attacks by triggering -// a stack overflow, there is a recursion limit. This limit is -// a sanity check to make sure it doesn't run the risk of -// busting the stack. +// For this reason, in order to avoid DoS attacks by triggering a stack +// overflow, there is a recursion limit. This limit is a sanity check to make +// sure it doesn't run the risk of busting the stack. // -// The second mechanism is bdecode(), which returns a -// bencoded structure represented by bdecode_node. This function -// builds a tree that points back into the original buffer. -// The returned bdecode_node will not be valid once the buffer -// it was parsed out of is discarded. +// The second mechanism is the decode function for bdecode_node. This function +// builds a tree that points back into the original buffer. The returned +// bdecode_node will not be valid once the buffer it was parsed out of is +// discarded. // -// Not only is this function more efficient because of less -// memory allocation and data copy, the parser is also not -// recursive, which means it probably performs a little bit -// better and can have a higher recursion limit on the structures -// it's parsing. +// Not only is this function more efficient because of less memory allocation +// and data copy, the parser is also not recursive, which means it probably +// performs a little bit better and can have a higher recursion limit on the +// structures it's parsing. #include #include diff --git a/include/libtorrent/block_cache.hpp b/include/libtorrent/block_cache.hpp index 066756023..0ab4d5dbd 100644 --- a/include/libtorrent/block_cache.hpp +++ b/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); diff --git a/include/libtorrent/escape_string.hpp b/include/libtorrent/escape_string.hpp index b87c2f9ed..cbd8cd201 100644 --- a/include/libtorrent/escape_string.hpp +++ b/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 - // returns it. + // The overload taking a ``std::string`` converts (binary) the string ``s`` + // 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 diff --git a/include/libtorrent/peer_info.hpp b/include/libtorrent/peer_info.hpp index 84dad29ed..5f8054336 100644 --- a/include/libtorrent/peer_info.hpp +++ b/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 diff --git a/include/libtorrent/sha1_hash.hpp b/include/libtorrent/sha1_hash.hpp index 1dc1f05e7..439726d39 100644 --- a/include/libtorrent/sha1_hash.hpp +++ b/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); diff --git a/include/libtorrent/string_util.hpp b/include/libtorrent/string_util.hpp index a6420b66e..ac2545685 100644 --- a/include/libtorrent/string_util.hpp +++ b/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); diff --git a/include/libtorrent/utf8.hpp b/include/libtorrent/utf8.hpp index 2a875d6b9..9490b3551 100644 --- a/include/libtorrent/utf8.hpp +++ b/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 diff --git a/src/entry.cpp b/src/entry.cpp index d7402c942..028ead032 100644 --- a/src/entry.cpp +++ b/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); - if (i == dict().end()) throw type_error( - (std::string("key not found: ") + key).c_str()); - return i->second; + return (*this)[std::string(key)]; } 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 diff --git a/src/string_util.cpp b/src/string_util.cpp index 2ffce0e48..60d0567fe 100644 --- a/src/string_util.cpp +++ b/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;