premiere
/
premiere-libtorrent
2
2
Fork 1
Code Issues Pull Requests Releases Wiki Activity

fix the documentation generation tool to work for flags, and other global constants. Improve documentation

This commit is contained in:
Arvid Norberg 2019-12-18 14:08:01 +01:00 committed by Arvid Norberg
parent 8378c0f55c
commit 55460a60bc
33 changed files with 279 additions and 112 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

144
docs/gen_reference_doc.py
View File

@ -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<span style="float:right;">[<a style="color:blue;" ' +
'href="http://github.com/arvidn/libtorrent/issues/new?title=docs:%s&labels=' +
'documentation&body=%s">report issue</a>]</span>\n\n').format(
'href="http://github.com/arvidn/libtorrent/issues/new?title=docs:{0}&labels=' +
'documentation&body={1}">report issue</a>]</span>\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<a name="%s"></a>\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<a name="%s::%s"></a>\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:

38
docs/hunspell/libtorrent.dic
View File

@ -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

1
docs/join_rst.py
View File

@ -1,4 +1,5 @@
#!/bin/python
# vim: tabstop=8 expandtab shiftwidth=4 softtabstop=4
import sys

6
docs/makefile
View File

@ -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;

5
docs/manual.rst
View File

@ -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

2
include/libtorrent/add_torrent_params.hpp
View File

@ -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"

18
include/libtorrent/alert_types.hpp
View File

@ -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
{

1
include/libtorrent/broadcast_socket.hpp
View File

@ -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 <typename Endpoint>
bool is_v4(Endpoint const& ep)

4
include/libtorrent/config.hpp
View File

@ -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

12
include/libtorrent/create_torrent.hpp
View File

@ -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<bool(std::string)> p, create_flags_t flags = {});

3
include/libtorrent/disk_interface.hpp
View File

@ -58,6 +58,7 @@ namespace libtorrent {
using file_open_mode_t = flags::bitfield_flag<std::uint8_t, struct file_open_mode_tag>;
// 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.

8
include/libtorrent/download_priority.hpp
View File

@ -39,9 +39,17 @@ namespace libtorrent {
using download_priority_t = aux::strong_typedef<std::uint8_t, struct download_priority_tag>;
// 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};
}

34
include/libtorrent/error_code.hpp
View File

@ -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

4
include/libtorrent/extensions.hpp
View File

@ -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_plugin> (*)(torrent_handle const&, void*);
//

2
include/libtorrent/extensions/ut_metadata.hpp
View File

@ -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.

1
include/libtorrent/file.hpp
View File

@ -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

18
include/libtorrent/fingerprint.hpp
View File

@ -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_.

1
include/libtorrent/http_connection.hpp
View File

@ -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<void(error_code const&

7
include/libtorrent/kademlia/announce_flags.hpp
View File

@ -43,8 +43,15 @@ using announce_flags_t = flags::bitfield_flag<std::uint8_t, struct dht_announce_
namespace announce {
// announce to DHT as a seed
constexpr announce_flags_t seed = 0_bit;
// announce to DHT with the implied-port flag set. This tells the network to use
// your source UDP port as your listen port, rather than the one specified in
// the message. This may improve the chances of traversing NATs when using uTP.
constexpr announce_flags_t implied_port = 1_bit;
// Specify the port number for the SSL listen socket in the DHT announce.
constexpr announce_flags_t ssl_torrent = 2_bit;
}

1
include/libtorrent/packet_pool.hpp
View File

@ -52,7 +52,6 @@ namespace libtorrent {
constexpr int TORRENT_UDP_HEADER = 8;
constexpr int TORRENT_UTP_HEADER = 20;
constexpr int TORRENT_SOCKS5_HEADER = 6; // plus the size of the destination address
constexpr int TORRENT_ETHERNET_MTU = 1500;
constexpr int TORRENT_TEREDO_MTU = 1280;
constexpr int TORRENT_INET_MIN_MTU = 576;

4
include/libtorrent/part_file.hpp
View File

@ -51,8 +51,8 @@ namespace libtorrent {
struct TORRENT_EXTRA_EXPORT part_file
{
// create a part file at 'path', that can hold 'num_pieces' pieces.
// each piece being 'piece_size' number of bytes
// create a part file at ``path``, that can hold ``num_pieces`` pieces.
// each piece being ``piece_size`` number of bytes
part_file(std::string const& path, std::string const& name, int num_pieces, int piece_size);
~part_file();

11
include/libtorrent/pex_flags.hpp
View File

@ -41,11 +41,18 @@ namespace libtorrent {
using pex_flags_t = flags::bitfield_flag<std::uint8_t, struct pex_flags_tag>;
// 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;
}

2
include/libtorrent/session_handle.hpp
View File

@ -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 = {});

4
include/libtorrent/settings_pack.hpp
View File

@ -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

4
include/libtorrent/storage.hpp
View File

@ -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<iovec_t const> bufs
, piece_index_t piece, int offset, open_mode_t flags, storage_error& ec) = 0;
virtual int writev(span<iovec_t const> bufs

2
include/libtorrent/storage_defs.hpp
View File

@ -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&);
}

4
include/libtorrent/string_util.hpp
View File

@ -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

14
include/libtorrent/torrent_flags.hpp
View File

@ -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

27
include/libtorrent/torrent_handle.hpp
View File

@ -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<char>(out), *rd->resume_data);
// std::vector<char> 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<torrent> native_handle() const;
private:

2
include/libtorrent/torrent_status.hpp
View File

@ -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.

2
include/libtorrent/upnp.hpp
View File

@ -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

3
include/libtorrent/utf8.hpp
View File

@ -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

2
test/test_resume.cpp
View File

@ -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.