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.