From cd5af8897a437143c2317cb628de50794205b676 Mon Sep 17 00:00:00 2001 From: Arvid Norberg Date: Fri, 29 Nov 2013 05:29:39 +0000 Subject: [PATCH] a bunch of documentation fixes --- docs/gen_reference_doc.py | 76 ++++++++++------ include/libtorrent/add_torrent_params.hpp | 3 + include/libtorrent/error_code.hpp | 1 + include/libtorrent/extensions.hpp | 10 ++- include/libtorrent/extensions/lt_trackers.hpp | 4 + .../extensions/metadata_transfer.hpp | 12 ++- include/libtorrent/extensions/smart_ban.hpp | 7 ++ include/libtorrent/extensions/ut_metadata.hpp | 10 +++ include/libtorrent/extensions/ut_pex.hpp | 9 ++ include/libtorrent/file_storage.hpp | 1 + include/libtorrent/ip_filter.hpp | 17 ++++ include/libtorrent/peer_info.hpp | 84 +++++++++-------- include/libtorrent/peer_request.hpp | 3 + include/libtorrent/ptime.hpp | 16 +--- include/libtorrent/session.hpp | 5 +- include/libtorrent/session_status.hpp | 43 +++++++-- include/libtorrent/settings.hpp | 9 +- include/libtorrent/sha1_hash.hpp | 5 +- include/libtorrent/storage.hpp | 17 ++-- include/libtorrent/storage_defs.hpp | 5 ++ include/libtorrent/torrent_handle.hpp | 90 +++++++++++-------- include/libtorrent/torrent_info.hpp | 12 +-- include/libtorrent/utp_stream.hpp | 3 +- src/torrent_handle.cpp | 6 -- 24 files changed, 297 insertions(+), 151 deletions(-) diff --git a/docs/gen_reference_doc.py b/docs/gen_reference_doc.py index 128f3a272..345453308 100644 --- a/docs/gen_reference_doc.py +++ b/docs/gen_reference_doc.py @@ -305,13 +305,12 @@ def parse_class(lno, lines, filename): print 'WARNING: member function "%s" is not documented: \x1b[34m%s:%d\x1b[0m' \ % (name + '::' + first_item(current_fun['names']), filename, lno) funs.append(current_fun) - context = '' - blanks = 0 + context = '' + blanks = 0 continue if looks_like_variable(l): if not is_visible(context): - context = '' continue n = l.split(' ')[-1].split(':')[0].split(';')[0] if context == '' and blanks == 0 and len(fields): @@ -327,14 +326,17 @@ def parse_class(lno, lines, filename): continue if l.startswith('enum '): - enum, lno = parse_enum(lno - 1, lines, filename) - if enum != None and is_visible(context): - enum['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) - enums.append(enum) - context = '' + if not is_visible(context): + consume_block(lno - 1, lines) + else: + enum, lno = parse_enum(lno - 1, lines, filename) + if enum != None: + enum['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) + enums.append(enum) + context = '' continue context = '' @@ -441,6 +443,13 @@ def consume_comment(lno, lines): return lno +def trim_define(l): + return l.replace('#ifndef', '').replace('#ifdef', '') \ + .replace('#if', '').replace('defined', '') \ + .replace('TORRENT_USE_IPV6', '').replace('TORRENT_NO_DEPRECATE', '') \ + .replace('||', '').replace('&&', '').replace('(', '').replace(')','') \ + .replace('!', '').rHTTP/1.1 200 OK Set-Cookie: i_like_gitea=68c31ff1a83dee09; Path=/; HttpOnly; Secure; SameSite=Lax Set-Cookie: _csrf=9EmxUH0HBe8fuJbJj8LB1d_QhRs6MTc1MzI2OTI0ODY1NzYzOTc1MA; Path=/; Max-Age=86400; HttpOnly; Secure; SameSite=Lax X-Frame-Options: SAMEORIGIN Date: Wed, 23 Jul 2025 11:14:08 GMT Content-Type: text/plain; charset=utf-8 Connection: close Transfer-Encoding: chunked Cache-Control: max-age=0, private, must-revalidate, no-transform X-Cache-Status: HIT X-Cache-Age: 0 5000 From cd5af8897a437143c2317cb628de50794205b676 Mon Sep 17 00:00:00 2001 From: Arvid Norberg Date: Fri, 29 Nov 2013 05:29:39 +0000 Subject: [PATCH] a bunch of documentation fixes --- docs/gen_reference_doc.py | 76 ++++++++++------ include/libtorrent/add_torrent_params.hpp | 3 + include/libtorrent/error_code.hpp | 1 + include/libtorrent/extensions.hpp | 10 ++- include/libtorrent/extensions/lt_trackers.hpp | 4 + .../extensions/metadata_transfer.hpp | 12 ++- include/libtorrent/extensions/smart_ban.hpp | 7 ++ include/libtorrent/extensions/ut_metadata.hpp | 10 +++ include/libtorrent/extensions/ut_pex.hpp | 9 ++ include/libtorrent/file_storage.hpp | 1 + include/libtorrent/ip_filter.hpp | 17 ++++ include/libtorrent/peer_info.hpp | 84 +++++++++-------- include/libtorrent/peer_request.hpp | 3 + include/libtorrent/ptime.hpp | 16 +--- include/libtorrent/session.hpp | 5 +- include/libtorrent/session_status.hpp | 43 +++++++-- include/libtorrent/settings.hpp | 9 +- include/libtorrent/sha1_hash.hpp | 5 +- include/libtorrent/storage.hpp | 17 ++-- include/libtorrent/storage_defs.hpp | 5 ++ include/libtorrent/torrent_handle.hpp | 90 +++++++++++-------- include/libtorrent/torrent_info.hpp | 12 +-- include/libtorrent/utp_stream.hpp | 3 +- src/torrent_handle.cpp | 6 -- 24 files changed, 297 insertions(+), 151 deletions(-) diff --git a/docs/gen_reference_doc.py b/docs/gen_reference_doc.py index 128f3a272..345453308 100644 --- a/docs/gen_reference_doc.py +++ b/docs/gen_reference_doc.py @@ -305,13 +305,12 @@ def parse_class(lno, lines, filename): print 'WARNING: member function "%s" is not documented: \x1b[34m%s:%d\x1b[0m' \ % (name + '::' + first_item(current_fun['names']), filename, lno) funs.append(current_fun) - context = '' - blanks = 0 + context = '' + blanks = 0 continue if looks_like_variable(l): if not is_visible(context): - context = '' continue n = l.split(' ')[-1].split(':')[0].split(';')[0] if context == '' and blanks == 0 and len(fields): @@ -327,14 +326,17 @@ def parse_class(lno, lines, filename): continue if l.startswith('enum '): - enum, lno = parse_enum(lno - 1, lines, filename) - if enum != None and is_visible(context): - enum['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) - enums.append(enum) - context = '' + if not is_visible(context): + consume_block(lno - 1, lines) + else: + enum, lno = parse_enum(lno - 1, lines, filename) + if enum != None: + enum['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) + enums.append(enum) + context = '' continue context = '' @@ -441,6 +443,13 @@ def consume_comment(lno, lines): return lno +def trim_define(l): + return l.replace('#ifndef', '').replace('#ifdef', '') \ + .replace('#if', '').replace('defined', '') \ + .replace('TORRENT_USE_IPV6', '').replace('TORRENT_NO_DEPRECATE', '') \ + .replace('||', '').replace('&&', '').replace('(', '').replace(')','') \ + .replace('!', '').r 1000 punch mechanism. + // This flag is set if the peer was in holepunch mode + // when the connection succeeded. This typically only + // happens if both peers are behind a NAT and the peers + // connect via the NAT holepunch mechanism. holepunched = 0x8000, + // indicates that this socket is runnin on top of the + // I2P transport. i2p_socket = 0x10000, + + // indicates that this socket is a uTP socket utp_socket = 0x20000, + + // this connection is obfuscated with RC4 rc4_encrypted = 0x100000, + + // the handshake of this connection was obfuscated + // with a diffie-hellman exchange plaintext_encrypted = 0x200000 }; @@ -136,6 +147,9 @@ namespace libtorrent // any combination of the peer_flags_t enum. unsigned int flags; + // the flags indicating which sources a peer can + // have come from. A peer may have been seen from + // multiple sources enum peer_source_flags { // The peer was received from the tracker. diff --git a/include/libtorrent/peer_request.hpp b/include/libtorrent/peer_request.hpp index 5ac535957..57e82ce36 100644 --- a/include/libtorrent/peer_request.hpp +++ b/include/libtorrent/peer_request.hpp @@ -35,6 +35,9 @@ POSSIBILITY OF SUCH DAMAGE. namespace libtorrent { + + // represents a byte range within a piece. Internally this is + // is used for incoming piece requests. struct TORRENT_EXPORT peer_request { // the index of the piece in which the range starts. diff --git a/include/libtorrent/ptime.hpp b/include/libtorrent/ptime.hpp index fcca0c0ec..28edacca8 100644 --- a/include/libtorrent/ptime.hpp +++ b/include/libtorrent/ptime.hpp @@ -57,7 +57,9 @@ namespace libtorrent // libtorrent time_duration type struct TORRENT_EXPORT time_duration { + // hidden time_duration() {} + time_duration operator/(int rhs) const { return time_duration(diff / rhs); } explicit time_duration(boost::int64_t d) : diff(d) {} time_duration& operator-=(time_duration const& c) { diff -= c.diff; return *this; } @@ -73,8 +75,10 @@ namespace libtorrent // This type represents a point in time. struct TORRENT_EXPORT ptime { + // hidden ptime() {} explicit ptime(boost::uint64_t t): time(t) {} + ptime& operator+=(time_duration rhs) { time += rhs.diff; return *this; } ptime& operator-=(time_duration rhs) { time -= rhs.diff; return *this; } @@ -87,40 +91,28 @@ namespace libtorrent // hidden inline bool operator>(ptime lhs, ptime rhs) { return lhs.time > rhs.time; } - // hidden inline bool operator>=(ptime lhs, ptime rhs) { return lhs.time >= rhs.time; } - // hidden inline bool operator<=(ptime lhs, ptime rhs) { return lhs.time <= rhs.time; } - // hidden inline bool operator<(ptime lhs, ptime rhs) { return lhs.time < rhs.time; } - // hidden inline bool operator!=(ptime lhs, ptime rhs) { return lhs.time != rhs.time;} - // hidden inline bool operator==(ptime lhs, ptime rhs) { return lhs.time == rhs.time;} - // hidden inline bool operator==(time_duration lhs, time_duration rhs) { return lhs.diff == rhs.diff; } - // hidden inline bool operator<(time_duration lhs, time_duration rhs) { return lhs.diff < rhs.diff; } - // hidden inline bool operator<=(time_duration lhs, time_duration rhs) { return lhs.diff <= rhs.diff; } - // hidden inline bool operator>(time_duration lhs, time_duration rhs) { return lhs.diff > rhs.diff; } - // hidden inline bool operator>=(time_duration lhs, time_duration rhs) { return lhs.diff >= rhs.diff; } - // hidden inline time_duration operator*(time_duration lhs, int rhs) { return time_duration(boost::int64_t(lhs.diff * rhs)); } - // hidden inline time_duration operator*(int lhs, time_duration rhs) { return time_duration(boost::int64_t(lhs * rhs.diff)); } diff --git a/include/libtorrent/session.hpp b/include/libtorrent/session.hpp index 6469f8cb0..cde629828 100644 --- a/include/libtorrent/session.hpp +++ b/include/libtorrent/session.hpp @@ -261,6 +261,7 @@ namespace libtorrent // is on by default. See add_torrent_params_. void post_torr 1000 ent_updates(); + // internal io_service& get_io_service(); // ``find_torrent()`` looks for a torrent with the given info-hash. In case there @@ -523,17 +524,17 @@ namespace libtorrent void load_asnum_db(char const* file); void load_country_db(char const* file); int as_for_ip(address const& addr); +#ifndef TORRENT_NO_DEPRECATE #if TORRENT_USE_WSTRING // all wstring APIs are deprecated since 0.16.11 // instead, use the wchar -> utf8 conversion functions // and pass in utf8 strings -#ifndef TORRENT_NO_DEPRECATE TORRENT_DEPRECATED_PREFIX void load_country_db(wchar_t const* file) TORRENT_DEPRECATED; TORRENT_DEPRECATED_PREFIX void load_asnum_db(wchar_t const* file) TORRENT_DEPRECATED; -#endif // TORRENT_NO_DEPRECATE #endif // TORRENT_USE_WSTRING +#endif // TORRENT_NO_DEPRECATE #endif // TORRENT_DISABLE_GEO_IP #ifndef TORRENT_NO_DEPRECATE diff --git a/include/libtorrent/session_status.hpp b/include/libtorrent/session_status.hpp index 6777699ef..47368586c 100644 --- a/include/libtorrent/session_status.hpp +++ b/include/libtorrent/session_status.hpp @@ -40,18 +40,43 @@ POSSIBILITY OF SUCH DAMAGE. namespace libtorrent { - struct dht_lookup + // holds statistics about a current dht_lookup operation. + // a DHT lookup is the travesal of nodes, looking up a + // set of target nodes in the DHT for retrieving and possibly + // storing information in the DHT + struct TORRENT_EXPORT dht_lookup { + // string literal indicating which kind of lookup this is char const* type; + + // the number of outstanding request to individual nodes + // this lookup has right now int outstanding_requests; + + // the total number of requests that have timed out so far + // for this lookup int timeouts; + + // the total number of responses we have received for this + // lookup so far for this lookup int responses; + + // the branch factor for this lookup. This is the number of + // nodes we keep outstanding requests to in parallel by default. + // when nodes time out we may increase this. int branch_factor; + + // the number of nodes left that could be queries for this + // lookup. Many of these are likely to be part of the trail + // while performing the lookup and would never end up actually + // being queried. int nodes_left; + // the number of seconds ago the // last message was sent that's still // outstanding int last_sent; + // the number of outstanding requests // that have exceeded the short timeout // and are considered timed out in the @@ -60,24 +85,31 @@ namespace libtorrent int first_timeout; }; - struct dht_routing_bucket + // holds dht routing table stats + struct TORRENT_EXPORT dht_routing_bucket { + // the total number of nodes and replacement nodes + // in the routing table int num_nodes; int num_replacements; + // number of seconds since last activity int last_active; }; - struct utp_status + // holds counters and gauges for the uTP sockets + struct TORRENT_EXPORT utp_status { - // gauges + // gauges. These are snapshots of the number of + // uTP sockets in each respective state int num_idle; int num_syn_sent; int num_connected; int num_fin_sent; int num_close_wait; - // counters + // counters. These are monotonically increasing + // and cumulative counters for their respective event. boost::uint64_t packet_loss; boost::uint64_t timeout; boost::uint64_t packets_in; @@ -92,6 +124,7 @@ namespace libtorrent boost::uint64_t redundant_pkts_in; }; + // contains session wide