From 55460a60bc722f27d1300bddd9743d4d59492da7 Mon Sep 17 00:00:00 2001 From: Arvid Norberg Date: Wed, 18 Dec 2019 14:08:01 +0100 Subject: [PATCH] fix the documentation generation tool to work for flags, and other global constants. Improve documentation --- docs/gen_reference_doc.py | 144 ++++++++++++++---- docs/hunspell/libtorrent.dic | 38 ++++- docs/join_rst.py | 1 + docs/makefile | 6 +- docs/manual.rst | 5 +- include/libtorrent/add_torrent_params.hpp | 2 +- include/libtorrent/alert_types.hpp | 18 ++- include/libtorrent/broadcast_socket.hpp | 1 + include/libtorrent/config.hpp | 4 + include/libtorrent/create_torrent.hpp | 12 +- include/libtorrent/disk_interface.hpp | 3 +- include/libtorrent/download_priority.hpp | 8 + include/libtorrent/error_code.hpp | 34 ++--- include/libtorrent/extensions.hpp | 4 +- include/libtorrent/extensions/ut_metadata.hpp | 2 +- include/libtorrent/file.hpp | 1 + include/libtorrent/fingerprint.hpp | 18 +-- include/libtorrent/http_connection.hpp | 1 + .../libtorrent/kademlia/announce_flags.hpp | 7 + include/libtorrent/packet_pool.hpp | 1 - include/libtorrent/part_file.hpp | 4 +- include/libtorrent/pex_flags.hpp | 11 +- include/libtorrent/session_handle.hpp | 2 + include/libtorrent/settings_pack.hpp | 4 +- include/libtorrent/storage.hpp | 4 +- include/libtorrent/storage_defs.hpp | 2 +- include/libtorrent/string_util.hpp | 4 +- include/libtorrent/torrent_flags.hpp | 14 +- include/libtorrent/torrent_handle.hpp | 27 +--- include/libtorrent/torrent_status.hpp | 2 +- include/libtorrent/upnp.hpp | 2 +- include/libtorrent/utf8.hpp | 3 +- test/test_resume.cpp | 2 +- 33 files changed, 279 insertions(+), 112 deletions(-) diff --git a/docs/gen_reference_doc.py b/docs/gen_reference_doc.py index 1edd80876..95bb545bb 100644 --- a/docs/gen_reference_doc.py +++ b/docs/gen_reference_doc.py @@ -28,6 +28,7 @@ for p in paths: functions = [] classes = [] enums = [] +constants = {} # maps filename to overview description overviews = {} @@ -251,6 +252,17 @@ def looks_like_variable(line): return False +def looks_like_constant(line): + line = line.strip() + if line.startswith('inline'): + line = line.split('inline')[1] + line = line.strip() + if not line.startswith('constexpr'): + return False + line = line.split('constexpr')[1] + return looks_like_variable(line) + + def looks_like_forward_decl(line): line = line.split('//')[0] line = line.strip() @@ -338,6 +350,27 @@ def parse_function(lno, lines, filename): return [None, lno] +def add_desc(line): + # plain output prints just descriptions and filters out c++ code. + # it's used to run spell checker over + if plain_output: + for s in line.split('\n'): + # if the first character is a space, strip it + if len(s) > 0 and s[0] == ' ': + s = s[1:] + global in_code + if in_code is not None and not s.startswith(in_code) and len(s) > 1: + in_code = None + + if s.strip().startswith('.. code::'): + in_code = s.split('.. code::')[0] + '\t' + + # strip out C++ code from the plain text output since it's meant for + # running spell checking over + if not s.strip().startswith('.. ') and in_code is None: + plain_file.write(s + '\n') + + def parse_class(lno, lines, filename): start_brace = 0 end_brace = 0 @@ -404,24 +437,6 @@ def parse_class(lno, lines, filename): if verbose: print('desc %s' % line) - # plain output prints just descriptions and filters out c++ code. - # it's used to run spell checker over - if plain_output: - s = line.split('//')[1] - # if the first character is a space, strip it - if len(s) > 0 and s[0] == ' ': - s = s[1:] - global in_code - if in_code is not None and not s.startswith(in_code) and len(s) > 1: - in_code = None - - if s.strip().startswith('.. code::'): - in_code = s.split('.. code::')[0] + '\t' - - # strip out C++ code from the plain text output since it's meant for - # running spell checking over - if not s.strip().startswith('.. ') and in_code is None: - plain_file.write(s + '\n') line = line[2:] if len(line) and line[0] == ' ': line = line[1:] @@ -465,6 +480,7 @@ def parse_class(lno, lines, filename): print('TODO comment in public documentation: %s:%d' % (filename, lno)) sys.exit(1) current_fun['desc'] = context + add_desc(context) if context == '' and not suppress_warning(filename, first_item(current_fun['names'])): print('WARNING: member function "%s" is not documented: \x1b[34m%s:%d\x1b[0m' % (name + '::' + first_item(current_fun['names']), filename, lno)) @@ -491,6 +507,7 @@ def parse_class(lno, lines, filename): if context == '' and not suppress_warning(filename, n): print('WARNING: field "%s" is not documented: \x1b[34m%s:%d\x1b[0m' % (name + '::' + n, filename, lno)) + add_desc(context) fields.append({'signatures': [line], 'names': [n], 'desc': context}) context = '' blanks = 0 @@ -508,6 +525,7 @@ def parse_class(lno, lines, filename): print('TODO comment in public documentation: %s:%d' % (filename, lno)) sys.exit(1) enum['desc'] = context + add_desc(context) if context == '' and not suppress_warning(filename, enum['name']): print('WARNING: enum "%s" is not documented: \x1b[34m%s:%d\x1b[0m' % (name + '::' + enum['name'], filename, lno)) @@ -530,6 +548,19 @@ def parse_class(lno, lines, filename): return [None, lno] +def parse_constant(lno, lines, filename): + line = lines[lno].strip() + if verbose: + print('const %s' % line) + line = line.split('=')[0] + if 'constexpr' in line: + line = line.split('constexpr')[1] + if '{' in line and '}' in line: + line = line.split('{')[0] + t, name = line.strip().split(' ') + return [{'file': filename[11:], 'type': t, 'name': name}, lno + 1] + + def parse_enum(lno, lines, filename): start_brace = 0 end_brace = 0 @@ -597,6 +628,7 @@ def parse_enum(lno, lines, filename): if '=' in v: v = v.split('=')[0].strip() if is_visible(context): + add_desc(context) values.append({'name': v.strip(), 'desc': context, 'val': valstr}) if verbose: print('enumv %s' % valstr) @@ -800,6 +832,24 @@ for filename in files: print('xx %s' % line) continue + if looks_like_constant(line): + current_constant, lno = parse_constant(lno - 1, lines, filename) + if current_constant is not None and is_visible(context): + if 'TODO: ' in context: + print('TODO comment in public documentation: %s:%d' % (filename, lno)) + sys.exit(1) + current_constant['desc'] = context + add_desc(context) + if context == '': + print('WARNING: constant "%s" is not documented: \x1b[34m%s:%d\x1b[0m' + % (current_constant['name'], filename, lno)) + t = current_constant['type'] + if t in constants: + constants[t].append(current_constant) + else: + constants[t] = [current_constant] + continue + if 'TORRENT_EXPORT ' in line or line.startswith('inline ') or line.startswith('template') or internal: if line.startswith('class ') or line.startswith('struct '): if not line.endswith(';'): @@ -809,6 +859,7 @@ for filename in files: print('TODO comment in public documentation: %s:%d' % (filename, lno)) sys.exit(1) current_class['desc'] = context + add_desc(context) if context == '': print('WARNING: class "%s" is not documented: \x1b[34m%s:%d\x1b[0m' % (current_class['name'], filename, lno)) @@ -828,6 +879,7 @@ for filename in files: print('TODO comment in public documentation: %s:%d' % (filename, lno)) sys.exit(1) current_fun['desc'] = context + add_desc(context) if context == '': print('WARNING: function "%s" is not documented: \x1b[34m%s:%d\x1b[0m' % (first_item(current_fun['names']), filename, lno)) @@ -852,6 +904,7 @@ for filename in files: print('TODO comment in public documentation: %s:%d' % (filename, lno)) sys.exit(1) current_enum['desc'] = context + add_desc(context) if context == '': print('WARNING: enum "%s" is not documented: \x1b[34m%s:%d\x1b[0m' % (current_enum['name'], filename, lno)) @@ -879,6 +932,12 @@ for filename in files: # ==================================================================== +def new_category(cat): + return {'classes': [], 'functions': [], 'enums': [], + 'filename': 'reference-%s.rst' % cat.replace(' ', '_'), + 'constants': {}} + + if dump: if verbose: @@ -916,13 +975,15 @@ if dump: print(' %s' % v['name']) print('};') + for t, c in constants: + print('\x1b[4mconstant\x1b[0m %s %s\n' % (e['type'], e['name'])) + categories = {} for c in classes: cat = categorize_symbol(c['name'], c['file']) if cat not in categories: - categories[cat] = {'classes': [], 'functions': [], 'enums': [], - 'filename': 'reference-%s.rst' % cat.replace(' ', '_')} + categories[cat] = new_category(cat) if c['file'] in overviews: categories[cat]['overview'] = overviews[c['file']] @@ -950,8 +1011,7 @@ for c in classes: for f in functions: cat = categorize_symbol(first_item(f['names']), f['file']) if cat not in categories: - categories[cat] = {'classes': [], 'functions': [], 'enums': [], - 'filename': 'reference-%s.rst' % cat.replace(' ', '_')} + categories[cat] = new_category(cat) if f['file'] in overviews: categories[cat]['overview'] = overviews[f['file']] @@ -963,14 +1023,26 @@ for f in functions: for e in enums: cat = categorize_symbol(e['name'], e['file']) if cat not in categories: - categories[cat] = {'classes': [], 'functions': [], 'enums': [], - 'filename': 'reference-%s.rst' % cat.replace(' ', '_')} + categories[cat] = new_category(cat) categories[cat]['enums'].append(e) filename = categories[cat]['filename'].replace('.rst', '.html') + '#' symbols[e['name']] = filename + e['name'] for v in e['values']: symbols[e['name'] + '::' + v['name']] = filename + v['name'] +for t, c in constants.items(): + for const in c: + cat = categorize_symbol(t, const['file']) + if cat not in categories: + categories[cat] = new_category(cat) + if t not in categories[cat]['constants']: + categories[cat]['constants'][t] = [const] + else: + categories[cat]['constants'][t].append(const) + filename = categories[cat]['filename'].replace('.rst', '.html') + '#' + symbols[t + '::' + const['name']] = filename + t + '::' + const['name'] + symbols[t] = filename + t + def print_declared_in(out, o): out.write('Declared in "%s"\n\n' % print_link(o['file'], '../include/%s' % o['file'])) @@ -1162,6 +1234,8 @@ def print_toc(out, categories, s): print('\t| ' + print_link(n, symbols[n]), file=out) for e in categories[cat]['enums']: print('\t| ' + print_link(e['name'], symbols[e['name']]), file=out) + for t, c in categories[cat]['constants'].items(): + print('\t| ' + print_link(t, symbols[t]), file=out) print('', file=out) if 'overview' in categories[cat]: @@ -1171,8 +1245,8 @@ def print_toc(out, categories, s): def dump_report_issue(h, out): print(('.. raw:: html\n\n\t[report issue]\n\n').format( + 'href="http://github.com/arvidn/libtorrent/issues/new?title=docs:{0}&labels=' + + 'documentation&body={1}">report issue]\n\n').format( urllib.quote_plus(h), urllib.quote_plus('Documentation under heading "' + h + '" could be improved')), file=out) @@ -1199,6 +1273,7 @@ for cat in categories: classes = categories[cat]['classes'] functions = categories[cat]['functions'] enums = categories[cat]['enums'] + constants = categories[cat]['constants'] out.write('''.. include:: header.rst @@ -1321,6 +1396,23 @@ __ reference.html render_enums(out, enums, True, '-') + for t, c in constants.items(): + print('.. raw:: html\n', file=out) + print('\t\n' % t, file=out) + dump_report_issue(t, out) + print(heading(t, '-'), file=out) + print_declared_in(out, c[0]) + + for v in c: + print('.. raw:: html\n', file=out) + print('\t\n' % (t, v['name']), file=out) + print(v['name'], file=out) + v['desc'] = linkify_symbols(v['desc']) + print('\t%s' % v['desc'].replace('\n', '\n\t'), file=out) + print(dump_link_targets('\t'), file=out) + + print('', file=out) + print(dump_link_targets(), file=out) for i in static_links: diff --git a/docs/hunspell/libtorrent.dic b/docs/hunspell/libtorrent.dic index 52391d3ca..fee80d5a7 100644 --- a/docs/hunspell/libtorrent.dic +++ b/docs/hunspell/libtorrent.dic @@ -8,6 +8,7 @@ SHA-1 ed25519 const BEP +BEPs bdecode bdecoded bencode @@ -49,6 +50,7 @@ LRU LRUs UPnP NAT +NATs PMP arvid Arvid @@ -212,6 +214,7 @@ nid crypto URI URIs +uri infohashes rw holepunch @@ -438,6 +441,13 @@ todo 0x41727101980 0x7fffffffffffffff 2410d4554d5ed856d69f426c38791673c59f4418 +E4F0B674 +0DFC +48BB +98A5 +2AA730BDB6D6 +0x0 +0x20 2e 373ZDeQgQSQNuxdinNAPnQ63CRNn4iEXzg BT @@ -449,8 +459,6 @@ d11 de e1 impl -impl -impl md11 metadatai0ee metadatai1e6 @@ -513,3 +521,29 @@ chrono hunspell online dic +fallocate +strdup +istream +ostream +nonrouters +backoff +atime +wildcard +sk +OutIt +OutputIterator +udp +nat +pmp +https +RemoteHost +ExternalPort +ret +pos +os +bt +cpp +tos +BP +qB +LT1230 diff --git a/docs/join_rst.py b/docs/join_rst.py index f41007449..f2085d10a 100644 --- a/docs/join_rst.py +++ b/docs/join_rst.py @@ -1,4 +1,5 @@ #!/bin/python +# vim: tabstop=8 expandtab shiftwidth=4 softtabstop=4 import sys diff --git a/docs/makefile b/docs/makefile index 789f7eb3d..89c0f3e03 100644 --- a/docs/makefile +++ b/docs/makefile @@ -109,9 +109,9 @@ spell-check:plain_text_out.txt $(MANUAL_TARGETS:=.html) manual.rst settings.rst python filter-rst.py settings.rst >settings-plain.txt python filter-rst.py upgrade_to_1.2.rst >upgrade-1_2-plain.txt hunspell -d hunspell/en_US -p hunspell/libtorrent.dic -l plain_text_out.txt >hunspell-report.txt - hunspell -d hunspell/en_US -p hunspell/libtorrent.dic -l manual-plain.txt >hunspell-report.txt - hunspell -d hunspell/en_US -p hunspell/libtorrent.dic -l upgrade-1_2-plain.txt >hunspell-report.txt -# hunspell -d hunspell/en_US -p hunspell/settings.dic -l settings-plain.txt >hunspell-report.txt + hunspell -d hunspell/en_US -p hunspell/libtorrent.dic -l manual-plain.txt >>hunspell-report.txt + hunspell -d hunspell/en_US -p hunspell/libtorrent.dic -l upgrade-1_2-plain.txt >>hunspell-report.txt + hunspell -d hunspell/en_US -p hunspell/settings.dic -l settings-plain.txt >>hunspell-report.txt hunspell -d hunspell/en_US -p hunspell/libtorrent.dic -H -l $(MANUAL_TARGETS:=.html) >>hunspell-report.txt @if [ -s hunspell-report.txt ]; then echo 'spellcheck failed, fix words or add to dictionary:'; cat hunspell-report.txt; false; fi; diff --git a/docs/manual.rst b/docs/manual.rst index 7c33e8432..d44343201 100644 --- a/docs/manual.rst +++ b/docs/manual.rst @@ -204,8 +204,9 @@ resume torrents based on certain criteria. The criteria depends on the overall state the torrent is in (checking, downloading or seeding). To opt-out of the queuing logic, make sure your torrents are added with the -add_torrent_params::flag_auto_managed bit *cleared*. Or call -``torrent_handle::auto_managed(false)`` on the torrent handle. +torrent_flags::auto_managed bit *cleared* from ``add_torrent_params::flags``. +Or call ``torrent_handle::unset_flags(torrent_flags::auto_managed)`` on the +torrent handle. The overall purpose of the queuing logic is to improve performance under arbitrary torrent downloading and seeding load. For example, if you want to download 100 diff --git a/include/libtorrent/add_torrent_params.hpp b/include/libtorrent/add_torrent_params.hpp index d14be1406..5b08fcdca 100644 --- a/include/libtorrent/add_torrent_params.hpp +++ b/include/libtorrent/add_torrent_params.hpp @@ -80,7 +80,7 @@ TORRENT_VERSION_NAMESPACE_2 // // The ``add_torrent_params`` is also used when requesting resume data for a // torrent. It can be saved to and restored from a file and added back to a - // new session. For serialization and deserialization of + // new session. For serialization and de-serialization of // ``add_torrent_params`` objects, see read_resume_data() and // write_resume_data(). #include "libtorrent/aux_/disable_warnings_push.hpp" diff --git a/include/libtorrent/alert_types.hpp b/include/libtorrent/alert_types.hpp index b319bce7a..4a84638fb 100644 --- a/include/libtorrent/alert_types.hpp +++ b/include/libtorrent/alert_types.hpp @@ -436,9 +436,11 @@ TORRENT_VERSION_NAMESPACE_2 // or that our send buffer watermark is too small, because we can // send it all before the disk gets back to us. // The number of bytes that we keep outstanding, requested from the disk, is calculated - // as follows:: + // as follows: // - // min(512, max(upload_rate * send_buffer_watermark_factor / 100, send_buffer_watermark)) + // .. code:: C++ + // + // min(512, max(upload_rate * send_buffer_watermark_factor / 100, send_buffer_watermark)) // // If you receive this alert, you might want to either increase your ``send_buffer_watermark`` // or ``send_buffer_watermark_factor``. @@ -715,7 +717,7 @@ TORRENT_VERSION_NAMESPACE_2 std::string message() const override; }; - // This alert is generated when a peer is unsnubbed. Essentially when it was snubbed for stalling + // This alert is generated when a peer is un-snubbed. Essentially when it was snubbed for stalling // sending data, and now it started sending data again. struct TORRENT_EXPORT peer_unsnubbed_alert final : peer_alert { @@ -1325,7 +1327,9 @@ TORRENT_VERSION_NAMESPACE_2 // // Typically, when receiving this alert, you would want to save the torrent file in order // to load it back up again when the session is restarted. Here's an example snippet of - // code to do that:: + // code to do that: + // + // .. code:: c++ // // torrent_handle h = alert->handle(); // if (h.is_valid()) { @@ -1668,8 +1672,8 @@ TORRENT_VERSION_NAMESPACE_2 }; - // This alert is generated when a fastresume file has been passed to - // add_torrent() but the files on disk did not match the fastresume file. + // This alert is generated when a fast resume file has been passed to + // add_torrent() but the files on disk did not match the fast resume file. // The error_code explains the reason why the resume file was rejected. struct TORRENT_EXPORT fastresume_rejected_alert final : torrent_alert { @@ -2033,7 +2037,7 @@ TORRENT_VERSION_NAMESPACE_2 // This alert is always posted when a torrent was attempted to be added // and contains the return status of the add operation. The torrent handle of the new - // torrent can be found in the base class' ``handle`` member. If adding + // torrent can be found as the ``handle`` member in the base class. If adding // the torrent failed, ``error`` contains the error code. struct TORRENT_EXPORT add_torrent_alert final : torrent_alert { diff --git a/include/libtorrent/broadcast_socket.hpp b/include/libtorrent/broadcast_socket.hpp index 3637356f6..134c973bb 100644 --- a/include/libtorrent/broadcast_socket.hpp +++ b/include/libtorrent/broadcast_socket.hpp @@ -54,6 +54,7 @@ namespace libtorrent { TORRENT_EXTRA_EXPORT bool is_teredo(address const& addr); TORRENT_EXTRA_EXPORT bool is_ip_address(std::string const& host); + // internal // TODO: refactor these out too template bool is_v4(Endpoint const& ep) diff --git a/include/libtorrent/config.hpp b/include/libtorrent/config.hpp index fb8532426..207aa1e35 100644 --- a/include/libtorrent/config.hpp +++ b/include/libtorrent/config.hpp @@ -451,8 +451,10 @@ POSSIBILITY OF SUCH DAMAGE. #if !defined(TORRENT_READ_HANDLER_MAX_SIZE) # if defined _GLIBCXX_DEBUG || !defined NDEBUG +// internal constexpr std::size_t TORRENT_READ_HANDLER_MAX_SIZE = 432; # else +// internal // if this is not divisible by 8, we're wasting space constexpr std::size_t TORRENT_READ_HANDLER_MAX_SIZE = 342; # endif @@ -460,8 +462,10 @@ constexpr std::size_t TORRENT_READ_HANDLER_MAX_SIZE = 342; #if !defined(TORRENT_WRITE_HANDLER_MAX_SIZE) # if defined _GLIBCXX_DEBUG || !defined NDEBUG +// internal constexpr std::size_t TORRENT_WRITE_HANDLER_MAX_SIZE = 432; # else +// internal // if this is not divisible by 8, we're wasting space constexpr std::size_t TORRENT_WRITE_HANDLER_MAX_SIZE = 342; # endif diff --git a/include/libtorrent/create_torrent.hpp b/include/libtorrent/create_torrent.hpp index 83ca9ed08..923e75dee 100644 --- a/include/libtorrent/create_torrent.hpp +++ b/include/libtorrent/create_torrent.hpp @@ -369,7 +369,9 @@ namespace detail { // // If specified, the predicate ``p`` is called once for every file and directory that // is encountered. Files for which ``p`` returns true are added, and directories for - // which ``p`` returns true are traversed. ``p`` must have the following signature:: + // which ``p`` returns true are traversed. ``p`` must have the following signature: + // + // .. code:: c++ // // bool Pred(std::string const& p); // @@ -389,7 +391,9 @@ namespace detail { // This function will assume that the files added to the torrent file exists at path // ``p``, read those files and hash the content and set the hashes in the ``create_torrent`` // object. The optional function ``f`` is called in between every hash that is set. ``f`` - // must have the following signature:: + // must have the following signature: + // + // .. code:: c++ // // void Fun(piece_index_t); // @@ -417,11 +421,11 @@ namespace detail { } #endif +#if TORRENT_ABI_VERSION == 1 + // all wstring APIs are deprecated since 0.16.11 // instead, use the wchar -> utf8 conversion functions // and pass in utf8 strings -#if TORRENT_ABI_VERSION == 1 - TORRENT_DEPRECATED_EXPORT void add_files(file_storage& fs, std::wstring const& wfile , std::function p, create_flags_t flags = {}); diff --git a/include/libtorrent/disk_interface.hpp b/include/libtorrent/disk_interface.hpp index ab8f325a2..d662ab826 100644 --- a/include/libtorrent/disk_interface.hpp +++ b/include/libtorrent/disk_interface.hpp @@ -58,6 +58,7 @@ namespace libtorrent { using file_open_mode_t = flags::bitfield_flag; + // internal // this is a bittorrent constant constexpr int default_block_size = 0x4000; @@ -105,7 +106,7 @@ namespace libtorrent { // ``open_mode`` is a bitmask of the file flags this file is currently // opened with. These are the flags used in the ``file::open()`` function. - // The flags used in this bitfield are defined by the file_open_mode enum. + // For possible flags, see file_open_mode_t. // // Note that the read/write mode is not a bitmask. The two least significant bits are used // to represent the read/write mode. Those bits can be masked out using the ``rw_mask`` constant. diff --git a/include/libtorrent/download_priority.hpp b/include/libtorrent/download_priority.hpp index fb2108ac4..1b31427e4 100644 --- a/include/libtorrent/download_priority.hpp +++ b/include/libtorrent/download_priority.hpp @@ -39,9 +39,17 @@ namespace libtorrent { using download_priority_t = aux::strong_typedef; +// Don't download the file or piece. Partial pieces may still be downloaded when +// setting file priorities. constexpr download_priority_t dont_download{0}; + +// The default priority for files and pieces. constexpr download_priority_t default_priority{4}; + +// The lowest priority for files and pieces. constexpr download_priority_t low_priority{1}; + +// The highest priority for files and pieces. constexpr download_priority_t top_priority{7}; } diff --git a/include/libtorrent/error_code.hpp b/include/libtorrent/error_code.hpp index d8310df27..901baff55 100644 --- a/include/libtorrent/error_code.hpp +++ b/include/libtorrent/error_code.hpp @@ -111,7 +111,7 @@ namespace libtorrent { unsupported_url_protocol, // The URL did not conform to URL syntax and failed to be parsed url_parse_error, - // The peer sent a 'piece' message of length 0 + // The peer sent a piece message of length 0 peer_sent_empty_piece, // A bencoded structure was corrupt and failed to be parsed parse_failed, @@ -129,7 +129,7 @@ namespace libtorrent { // The port is blocked by the port-filter, and prevented the // connection port_blocked, - // The IPv6 address was expected to end with ']' + // The IPv6 address was expected to end with "]" expected_close_bracket_in_address, // The torrent is being destructed, preventing the operation to // succeed @@ -215,9 +215,9 @@ namespace libtorrent { sync_hash_not_found, // The encryption constant in the handshake is invalid invalid_encryption_constant, - // The peer does not support plaintext, which is the selected mode + // The peer does not support plain text, which is the selected mode no_plaintext_mode, - // The peer does not support rc4, which is the selected mode + // The peer does not support RC4, which is the selected mode no_rc4_mode, // The peer does not support any of the encryption modes that the // client supports @@ -349,11 +349,11 @@ namespace libtorrent { #endif - // The resume data file is missing the 'file sizes' entry + // The resume data file is missing the ``file sizes`` entry missing_file_sizes = 130, - // The resume data file 'file sizes' entry is empty + // The resume data file ``file sizes`` entry is empty no_files_in_resume_data, - // The resume data file is missing the 'pieces' and 'slots' entry + // The resume data file is missing the ``pieces`` and ``slots`` entry missing_pieces, // The number of files in the resume data does not match the number // of files in the torrent @@ -366,16 +366,16 @@ namespace libtorrent { mismatching_file_timestamp, // The resume data file is not a dictionary not_a_dictionary, - // The 'blocks per piece' entry is invalid in the resume data file + // The ``blocks per piece`` entry is invalid in the resume data file invalid_blocks_per_piece, - // The resume file is missing the 'slots' entry, which is required + // The resume file is missing the ``slots`` entry, which is required // for torrents with compact allocation. *DEPRECATED* missing_slots, // The resume file contains more slots than the torrent too_many_slots, - // The 'slot' entry is invalid in the resume data + // The ``slot`` entry is invalid in the resume data invalid_slot_list, - // One index in the 'slot' list is invalid + // One index in the ``slot`` list is invalid invalid_piece_index, // The pieces on disk needs to be re-ordered for the specified // allocation mode. This happens if you specify sparse allocation @@ -416,17 +416,17 @@ namespace libtorrent { invalid_peer_dict, // tracker sent a failure message tracker_failure, - // missing or invalid 'files' entry + // missing or invalid ``files`` entry invalid_files_entry, - // missing or invalid 'hash' entry + // missing or invalid ``hash`` entry invalid_hash_entry, - // missing or invalid 'peers' and 'peers6' entry + // missing or invalid ``peers`` and ``peers6`` entry invalid_peers_entry, - // udp tracker response packet has invalid size + // UDP tracker response packet has invalid size invalid_tracker_response_length, - // invalid transaction id in udp tracker response + // invalid transaction id in UDP tracker response invalid_tracker_transaction_id, - // invalid action field in udp tracker response + // invalid action field in UDP tracker response invalid_tracker_action, #if TORRENT_ABI_VERSION == 1 diff --git a/include/libtorrent/extensions.hpp b/include/libtorrent/extensions.hpp index 5aa7f0709..cea5f8c96 100644 --- a/include/libtorrent/extensions.hpp +++ b/include/libtorrent/extensions.hpp @@ -96,7 +96,9 @@ POSSIBILITY OF SUCH DAMAGE. // torrent has already been started and you want to hook in the extension at // run-time). // -// The signature of the function is:: +// The signature of the function is: +// +// .. code:: c++ // // std::shared_ptr (*)(torrent_handle const&, void*); // diff --git a/include/libtorrent/extensions/ut_metadata.hpp b/include/libtorrent/extensions/ut_metadata.hpp index 3fc9a97c7..efc29186a 100644 --- a/include/libtorrent/extensions/ut_metadata.hpp +++ b/include/libtorrent/extensions/ut_metadata.hpp @@ -46,7 +46,7 @@ namespace libtorrent { // constructor function for the ut_metadata extension. The ut_metadata // extension allows peers to request the .torrent file (or more - // specifically the 'info'-dictionary of the .torrent file) from each + // specifically the info-dictionary of the .torrent file) from each // other. This is the main building block in making magnet links work. // This extension is enabled by default unless explicitly disabled in // the session constructor. diff --git a/include/libtorrent/file.hpp b/include/libtorrent/file.hpp index cce185a66..224ff01e5 100644 --- a/include/libtorrent/file.hpp +++ b/include/libtorrent/file.hpp @@ -128,6 +128,7 @@ namespace libtorrent { // open the file for reading and writing constexpr open_mode_t read_write = 1_bit; + // the mask for the bits making up the read-write mode. constexpr open_mode_t rw_mask = read_only | write_only | read_write; // open the file in sparse mode (if supported by the diff --git a/include/libtorrent/fingerprint.hpp b/include/libtorrent/fingerprint.hpp index 956730dd5..afc26dc6e 100644 --- a/include/libtorrent/fingerprint.hpp +++ b/include/libtorrent/fingerprint.hpp @@ -52,23 +52,23 @@ namespace libtorrent { // +----------+-----------------------+ // | id chars | client | // +==========+=======================+ - // | 'LT' | libtorrent (default) | + // | LT | libtorrent (default) | // +----------+-----------------------+ - // | 'UT' | uTorrent | + // | UT | uTorrent | // +----------+-----------------------+ - // | 'UM' | uTorrent Mac | + // | UM | uTorrent Mac | // +----------+-----------------------+ - // | 'qB' | qBittorrent | + // | qB | qBittorrent | // +----------+-----------------------+ - // | 'BP' | BitTorrent Pro | + // | BP | BitTorrent Pro | // +----------+-----------------------+ - // | 'BT' | BitTorrent | + // | BT | BitTorrent | // +----------+-----------------------+ - // | 'DE' | Deluge | + // | DE | Deluge | // +----------+-----------------------+ - // | 'AZ' | Azureus | + // | AZ | Azureus | // +----------+-----------------------+ - // | 'TL' | Tribler | + // | TL | Tribler | // +----------+-----------------------+ // // There's an informal directory of client id's here_. diff --git a/include/libtorrent/http_connection.hpp b/include/libtorrent/http_connection.hpp index aee584608..3b17fd87a 100644 --- a/include/libtorrent/http_connection.hpp +++ b/include/libtorrent/http_connection.hpp @@ -64,6 +64,7 @@ namespace libtorrent { struct http_connection; struct resolver_interface; +// internal constexpr int default_max_bottled_buffer_size = 2 * 1024 * 1024; using http_handler = std::function; - // these flags match the flags passed in ut_pex - // messages + // the peer supports protocol encryption constexpr pex_flags_t pex_encryption = 1_bit; + + // the peer is a seed constexpr pex_flags_t pex_seed = 2_bit; + + // the peer supports the uTP, transport protocol over UDP. constexpr pex_flags_t pex_utp = 3_bit; + + // the peer supports the holepunch extension If this flag is received from a + // peer, it can be used as a rendezvous point in case direct connections to + // the peer fail constexpr pex_flags_t pex_holepunch = 4_bit; } diff --git a/include/libtorrent/session_handle.hpp b/include/libtorrent/session_handle.hpp index 22e3ae817..730ad9beb 100644 --- a/include/libtorrent/session_handle.hpp +++ b/include/libtorrent/session_handle.hpp @@ -468,6 +468,8 @@ namespace libtorrent { // Both these functions are exposed for advanced custom use of the DHT. // All torrents eligible to be announce to the DHT will be automatically, // by libtorrent. + // + // For possible flags, see announce_flags_t. void dht_get_peers(sha1_hash const& info_hash); void dht_announce(sha1_hash const& info_hash, int port = 0, dht::announce_flags_t flags = {}); diff --git a/include/libtorrent/settings_pack.hpp b/include/libtorrent/settings_pack.hpp index fa9263df5..cc3452c6f 100644 --- a/include/libtorrent/settings_pack.hpp +++ b/include/libtorrent/settings_pack.hpp @@ -719,7 +719,7 @@ namespace aux { enable_dht, // if the allowed encryption level is both, setting this to true will - // prefer rc4 if both methods are offered, plain text otherwise + // prefer RC4 if both methods are offered, plain text otherwise prefer_rc4, // if true, hostname lookups are done via the configured proxy (if @@ -1770,7 +1770,7 @@ namespace aux { { // use only plain text encryption pe_plaintext = 1, - // use only rc4 encryption + // use only RC4 encryption pe_rc4 = 2, // allow both pe_both = 3 diff --git a/include/libtorrent/storage.hpp b/include/libtorrent/storage.hpp index d11ca3115..a94fd57c5 100644 --- a/include/libtorrent/storage.hpp +++ b/include/libtorrent/storage.hpp @@ -90,7 +90,7 @@ namespace libtorrent { // before it's written to disk, and decrypting it when it's read again. // // The storage interface is based on pieces. Every read and write operation - // happens in the piece-space. Each piece fits 'piece_size' number + // happens in the piece-space. Each piece fits ``piece_size`` number // of bytes. All access is done by writing and reading whole or partial // pieces. // @@ -156,6 +156,8 @@ namespace libtorrent { // The number of bytes read or written should be returned, or -1 on // error. If there's an error, the ``storage_error`` must be filled out // to represent the error that occurred. + // + // For possible values of ``flags``, see open_mode_t. virtual int readv(span bufs , piece_index_t piece, int offset, open_mode_t flags, storage_error& ec) = 0; virtual int writev(span bufs diff --git a/include/libtorrent/storage_defs.hpp b/include/libtorrent/storage_defs.hpp index 9235924e0..18a61454a 100644 --- a/include/libtorrent/storage_defs.hpp +++ b/include/libtorrent/storage_defs.hpp @@ -135,7 +135,7 @@ namespace libtorrent { TORRENT_EXPORT storage_interface* disabled_storage_constructor(storage_params const&, file_pool&); // the constructor function for the "zero" storage. This will always read - // zeroes and ignore all writes. + // zeros and ignore all writes. TORRENT_EXPORT storage_interface* zero_storage_constructor(storage_params const&, file_pool&); } diff --git a/include/libtorrent/string_util.hpp b/include/libtorrent/string_util.hpp index ed3b0859e..9b5333295 100644 --- a/include/libtorrent/string_util.hpp +++ b/include/libtorrent/string_util.hpp @@ -118,8 +118,8 @@ namespace libtorrent { // strdup is not part of the C standard. Some systems // don't have it and it won't be available when building - // in strict ansi mode - char* allocate_string_copy(string_view str); + // in strict ANSI mode + TORRENT_EXTRA_EXPORT char* allocate_string_copy(string_view str); // searches for separator ('sep') in the string 'last'. // if found, returns the string_view representing the range from the start of diff --git a/include/libtorrent/torrent_flags.hpp b/include/libtorrent/torrent_flags.hpp index 9bfbb77f4..a71c9cbb0 100644 --- a/include/libtorrent/torrent_flags.hpp +++ b/include/libtorrent/torrent_flags.hpp @@ -61,8 +61,8 @@ namespace torrent_flags { // Setting ``seed_mode`` on a torrent without metadata (a // .torrent file) is a no-op and will be ignored. // - // It is not possible to *set* the `seed_mode` flag on a torrent after it has - // been added to as session. It is possible to *clear* it though. + // It is not possible to *set* the ``seed_mode`` flag on a torrent after it has + // been added to a session. It is possible to *clear* it though. constexpr torrent_flags_t seed_mode = 0_bit; // If ``upload_mode`` is set, the torrent will be initialized in @@ -126,6 +126,10 @@ namespace torrent_flags { // order is the order the torrents were added. They are all downloaded // in that order. For more details, see queuing_. constexpr torrent_flags_t auto_managed = 5_bit; + + // used in add_torrent_params to indicate that it's an error to attempt + // to add a torrent that's already in the session. If it's not considered an + // error, a handle to the existing torrent is returned. constexpr torrent_flags_t duplicate_is_error = 6_bit; // on by default and means that this torrent will be part of state @@ -185,7 +189,7 @@ namespace torrent_flags { // added to the list of trackers used by the torrent. // This flag is set by read_resume_data() if there are trackers present in // the resume data file. This effectively makes the trackers saved in the - // resume data take presedence over the original trackers. This includes if + // resume data take precedence over the original trackers. This includes if // there's an empty list of trackers, to support the case where they were // explicitly removed in the previous session. constexpr torrent_flags_t override_trackers = 11_bit; @@ -196,7 +200,7 @@ namespace torrent_flags { // list of web seeds used by the torrent. // This flag is set by read_resume_data() if there are web seeds present in // the resume data file. This effectively makes the web seeds saved in the - // resume data take presedence over the original ones. This includes if + // resume data take precedence over the original ones. This includes if // there's an empty list of web seeds, to support the case where they were // explicitly removed in the previous session. constexpr torrent_flags_t override_web_seeds = 12_bit; @@ -263,6 +267,8 @@ namespace torrent_flags { // set this flag to disable peer exchange for this torrent. constexpr torrent_flags_t disable_pex = 21_bit; + // all torrent flags combined. Can conveniently be used when creating masks + // for flags constexpr torrent_flags_t all = torrent_flags_t::all(); // internal diff --git a/include/libtorrent/torrent_handle.hpp b/include/libtorrent/torrent_handle.hpp index 92afcf7a3..850653147 100644 --- a/include/libtorrent/torrent_handle.hpp +++ b/include/libtorrent/torrent_handle.hpp @@ -727,8 +727,8 @@ namespace aux { // std::ofstream out((st.save_path // + "/" + st.name + ".fastresume").c_str() // , std::ios_base::binary); - // out.unsetf(std::ios_base::skipws); - // bencode(std::ostream_iterator(out), *rd->resume_data); + // std::vector buf = write_resume_data_buf(rd->params); + // out.write(buf.data(), buf.size()); // --outstanding_resume_data; // } // } @@ -993,7 +993,8 @@ namespace aux { // ``get_file_priorities()`` returns a vector with the priorities of all // files. // - // The priority values are the same as for piece_priority(). + // The priority values are the same as for piece_priority(). See + // download_priority_t. // // Whenever a file priority is changed, all other piece priorities are // reset to match the file priorities. In order to maintain special @@ -1101,21 +1102,7 @@ namespace aux { // Typically this is one of the source flags in peer_info. i.e. // ``tracker``, ``pex``, ``dht`` etc. // - // ``flags`` are the same flags that are passed along with the ``ut_pex`` extension. - // - // ==== ========================================== - // 0x01 peer supports encryption. - // - // 0x02 peer is a seed - // - // 0x04 supports uTP. If this is not set, the peer will only be contacted - // over TCP. - // - // 0x08 supports hole punching protocol. If this - // flag is received from a peer, it can be - // used as a rendezvous point in case direct - // connections to the peer fail - // ==== ========================================== + // For possible values of ``flags``, see pex_flags_t. void connect_peer(tcp::endpoint const& adr, peer_source_flags_t source = {} , pex_flags_t flags = pex_encryption | pex_utp | pex_holepunch) const; @@ -1252,7 +1239,9 @@ namespace aux { // This function is intended only for use by plugins and the alert // dispatch function. This type does not have a stable API and should - // be relied on as little as possible. + // be relied on as little as possible. Accessing the handle returned by + // this function is not thread safe outside of libtorrent's internal + // thread (which is used to invoke plugin callbacks). std::shared_ptr native_handle() const; private: diff --git a/include/libtorrent/torrent_status.hpp b/include/libtorrent/torrent_status.hpp index dae1a13ae..ede0e2e78 100644 --- a/include/libtorrent/torrent_status.hpp +++ b/include/libtorrent/torrent_status.hpp @@ -123,7 +123,7 @@ TORRENT_VERSION_NAMESPACE_2 // allocated. allocating, - // The torrent is currently checking the fastresume data and + // The torrent is currently checking the fast resume data and // comparing it to the files on disk. This is typically // completed in a fraction of a second, but if you add a // large number of torrents at once, they will queue up. diff --git a/include/libtorrent/upnp.hpp b/include/libtorrent/upnp.hpp index b24f5e261..e110e93cd 100644 --- a/include/libtorrent/upnp.hpp +++ b/include/libtorrent/upnp.hpp @@ -69,7 +69,7 @@ namespace libtorrent { // The source IP address cannot be wild-carded, but // must be fully specified source_ip_cannot_be_wildcarded = 715, - // The external port cannot be wildcarded, but must + // The external port cannot be a wildcard, but must // be specified external_port_cannot_be_wildcarded = 716, // The port mapping entry specified conflicts with a diff --git a/include/libtorrent/utf8.hpp b/include/libtorrent/utf8.hpp index 22f929ee1..b02f30aa1 100644 --- a/include/libtorrent/utf8.hpp +++ b/include/libtorrent/utf8.hpp @@ -46,6 +46,7 @@ namespace libtorrent { namespace utf8_errors { + // internal enum error_code_enum { // conversion successful @@ -54,7 +55,7 @@ namespace libtorrent { // partial character in source, but hit end source_exhausted, - // insuff. room in target for conversion + // insufficient room in target for conversion target_exhausted, // source sequence is illegal/malformed diff --git a/test/test_resume.cpp b/test/test_resume.cpp index 18d493141..9a7847d3d 100644 --- a/test/test_resume.cpp +++ b/test/test_resume.cpp @@ -543,7 +543,7 @@ TORRENT_TEST(piece_slots_seed_suggest_cache) } // TODO: test what happens when loading a resume file with both piece priorities -// and file priorities (file prio should take presedence) +// and file priorities (file prio should take precedence) // TODO: make sure a resume file only ever contain file priorities OR piece // priorities. Never both.