From 3258d92f64fa4928c637159e0502f8034eaaaf8d Mon Sep 17 00:00:00 2001 From: Arvid Norberg Date: Fri, 16 Aug 2013 05:07:09 +0000 Subject: [PATCH] added documentations to headers --- docs/gen_reference_doc.py | 18 ++++++ include/libtorrent/add_torrent_params.hpp | 6 ++ include/libtorrent/alert.hpp | 1 + include/libtorrent/create_torrent.hpp | 3 + include/libtorrent/lazy_entry.hpp | 77 +++++++++++++++++++---- include/libtorrent/rss.hpp | 1 + include/libtorrent/storage.hpp | 1 + include/libtorrent/storage_defs.hpp | 1 + include/libtorrent/thread.hpp | 2 + include/libtorrent/time.hpp | 12 ++++ include/libtorrent/torrent_handle.hpp | 12 ++-- 11 files changed, 117 insertions(+), 17 deletions(-) diff --git a/docs/gen_reference_doc.py b/docs/gen_reference_doc.py index 595ecb8f2..6163734bd 100644 --- a/docs/gen_reference_doc.py +++ b/docs/gen_reference_doc.py @@ -113,6 +113,15 @@ def categorize_symbol(name, filename): return 'Core' +def suppress_warning(filename, name): + f = os.path.split(filename)[1] + if f != 'alert_types.hpp': return False + +# if name.endswith('_alert') or name == 'message()': + return True + +# return False + def first_item(itr): for i in itr: return i @@ -285,6 +294,8 @@ def parse_class(lno, lines, filename): funs[-1]['names'].update(current_fun['names']) else: current_fun['desc'] = context + if context == '' and not suppress_warning(filename, first_item(current_fun['names'])): + print 'WARNING: member function "%s" is not documented' % (name + '::' + first_item(current_fun['names'])) funs.append(current_fun) context = '' blanks = 0 @@ -299,6 +310,8 @@ def parse_class(lno, lines, filename): fields[-1]['names'].append(n) fields[-1]['signatures'].append(l) else: + if context == '' and not suppress_warning(filename, n): + print 'WARNING: field "%s" is not documented' % (name + '::' + n) fields.append({'signatures': [l], 'names': [n], 'desc': context}) context = '' blanks = 0 @@ -308,6 +321,8 @@ def parse_class(lno, lines, filename): 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' % (name + '::' + enum['name']) enums.append(enum) context = '' continue @@ -510,6 +525,7 @@ for filename in files: current_class, lno = parse_class(lno -1, lines, filename) if current_class != None and is_visible(context): current_class['desc'] = context + if context == '': print 'WARNING: class "%s" is not documented' % (current_class['name']) classes.append(current_class) context = '' blanks += 1 @@ -523,6 +539,7 @@ for filename in files: functions[-1]['names'].update(current_fun['names']) else: current_fun['desc'] = context + if context == '': print 'WARNING: function "%s" is not documented' % (first_item(current_fun['names'])) functions.append(current_fun) blanks = 0 context = '' @@ -538,6 +555,7 @@ for filename in files: current_enum, lno = parse_enum(lno - 1, lines, filename) if current_enum != None and is_visible(context): current_enum['desc'] = context + if context == '': print 'WARNING: enum "%s" is not documented' % (current_enum['name']) enums.append(current_enum) context = '' blanks += 1 diff --git a/include/libtorrent/add_torrent_params.hpp b/include/libtorrent/add_torrent_params.hpp index 9a104d4b4..1423a1687 100644 --- a/include/libtorrent/add_torrent_params.hpp +++ b/include/libtorrent/add_torrent_params.hpp @@ -327,6 +327,12 @@ namespace libtorrent int download_limit; #ifndef TORRENT_DISABLE_EXTENSIONS + // torrent extension construction functions can be added to this + // vector to have them be added immediately when the torrent is + // constructed. This may be desired over the torrent_handle::add_extension() + // in order to avoid race conditions. For instance it may be important + // to have the plugin catch events that happen very early on after + // the torrent is created. std::vector(torrent*, void*)> > extensions; #endif }; diff --git a/include/libtorrent/alert.hpp b/include/libtorrent/alert.hpp index 897d4c421..191c73372 100644 --- a/include/libtorrent/alert.hpp +++ b/include/libtorrent/alert.hpp @@ -96,6 +96,7 @@ namespace libtorrent { enum severity_t { debug, info, warning, critical, fatal, none }; #endif + // these are bits for the alert_mask used by the session. See set_alert_mask(). enum category_t { // Enables alerts that report an error. This includes: diff --git a/include/libtorrent/create_torrent.hpp b/include/libtorrent/create_torrent.hpp index af9ad261d..9710e8839 100644 --- a/include/libtorrent/create_torrent.hpp +++ b/include/libtorrent/create_torrent.hpp @@ -172,6 +172,7 @@ namespace libtorrent , int pad_file_limit = -1, int flags = optimize, int alignment = 0x4000); create_torrent(torrent_info const& ti); + // internal ~create_torrent(); // This function will generate the .torrent file as a bencode tree. In order to @@ -199,6 +200,8 @@ namespace libtorrent // any files to the ``file_storage``, torrent generation will fail. entry generate() const; + // returns an immutable reference to the file_storage used to create + // the torrent from. file_storage const& files() const { return m_files; } // Sets the comment for the torrent. The string ``str`` should be utf-8 encoded. diff --git a/include/libtorrent/lazy_entry.hpp b/include/libtorrent/lazy_entry.hpp index 57970d753..25040109b 100644 --- a/include/libtorrent/lazy_entry.hpp +++ b/include/libtorrent/lazy_entry.hpp @@ -95,11 +95,21 @@ namespace libtorrent , lazy_entry& ret, int depth_limit = 1000, int item_limit = 1000000) TORRENT_DEPRECATED; #endif + // this is a string that is not NULL-terminated. Instead it + // comes with a length, specified in bytes. This is particularly + // useful when parsing bencoded structures, because strings are + // not NULL-terminated internally, and requiring NULL termination + // would require copying the string. + // + // see lazy_entry::string_pstr(). struct TORRENT_EXPORT pascal_string { pascal_string(char const* p, int l): len(l), ptr(p) {} int len; char const* ptr; + + // lexicographical comparison of strings. Order is consisten + // with memcmp. bool operator<(pascal_string const& rhs) const { return std::memcmp(ptr, rhs.ptr, (std::min)(len, rhs.len)) < 0 @@ -109,8 +119,19 @@ namespace libtorrent struct lazy_dict_entry; + // this object represent a node in a bencoded structure. It is a variant + // type whose concrete type is one of: + // + // 1. dictionary (maps strings -> lazy_entry) + // 2. list (sequence of lazy_entry, i.e. heterogenous) + // 3. integer + // 4. string + // + // There is also a ``none`` type, which is used for uninitialized + // lazy_entries. struct TORRENT_EXPORT lazy_entry { + // The different types a lazy_entry can have enum entry_type_t { none_t, dict_t, list_t, string_t, int_t @@ -119,6 +140,9 @@ namespace libtorrent lazy_entry() : m_begin(0), m_len(0), m_size(0), m_capacity(0), m_type(none_t) { m_data.start = 0; } + // tells you which specific type this lazy entry has. + // See entry_type_t. The type determines which subset of + // member functions are valid to use. entry_type_t type() const { return (entry_type_t)m_type; } // start points to the first decimal digit @@ -133,14 +157,15 @@ namespace libtorrent m_len = length + 2; // include 'e' } + // if this is an integer, return the integer value size_type int_value() const; - // string functions - // ================ - + // internal void construct_string(char const* start, int length); // the string is not null-terminated! + // use string_length() to determine how many bytes + // are part of the string. char const* string_ptr() const { TORRENT_ASSERT(m_type == string_t); @@ -156,24 +181,28 @@ namespace libtorrent return m_data.start; } + // if this is a string, returns a pascal_string + // representing the string value. pascal_string string_pstr() const { TORRENT_ASSERT(m_type == string_t); return pascal_string(m_data.start, m_size); } + // if this is a string, returns the string as a std::string. + // (which requires a copy) std::string string_value() const { TORRENT_ASSERT(m_type == string_t); return std::string(m_data.start, m_size); } + // if the lazy_entry is a string, returns the + // length of the string, in bytes. int string_length() const { return m_size; } - // dictionary functions - // ==================== - + // internal void construct_dict(char const* begin) { TORRENT_ASSERT(m_type == none_t); @@ -183,31 +212,45 @@ namespace libtorrent m_begin = begin; } + // internal lazy_entry* dict_append(char const* name); + // internal void pop(); + + // if this is a dictionary, look for a key ``name``, and return + // a pointer to its value, or NULL if there is none. lazy_entry* dict_find(char const* name); lazy_entry const* dict_find(char const* name) const { return const_cast(this)->dict_find(name); } + lazy_entry const* dict_find_string(char const* name) const; + // if this is a dictionary, look for a key ``name`` whose value + // is a string. If such key exist, return a pointer to + // its value, otherwise NULL. std::string dict_find_string_value(char const* name) const; pascal_string dict_find_pstr(char const* name) const; + + // if this is a dictionary, look for a key ``name`` whose value + // is an int. If such key exist, return a pointer to its value, + // otherwise NULL. size_type dict_find_int_value(char const* name, size_type default_val = 0) const; - lazy_entry const* dict_find_dict(char const* name) const; - lazy_entry const* dict_find_list(char const* name) const; - lazy_entry const* dict_find_string(char const* name) const; lazy_entry const* dict_find_int(char const* name) const; + lazy_entry const* dict_find_dict(char const* name) const; + lazy_entry const* dict_find_list(char const* name) const; + + // if this is a dictionary, return the key value pair at + // position ``i`` from the dictionary. std::pair dict_at(int i) const; + // if this is a dictionary, return the number of items in it int dict_size() const { TORRENT_ASSERT(m_type == dict_t); return m_size; } - // list functions - // ============== - + // internal void construct_list(char const* begin) { TORRENT_ASSERT(m_type == none_t); @@ -217,7 +260,10 @@ namespace libtorrent m_begin = begin; } + // internal lazy_entry* list_append(); + + // if this is a list, return the item at index ``i``. lazy_entry* list_at(int i) { TORRENT_ASSERT(m_type == list_t); @@ -231,19 +277,22 @@ namespace libtorrent pascal_string list_pstr_at(int i) const; size_type list_int_value_at(int i, size_type default_val = 0) const; + // if this is a list, return the number of items in it. int list_size() const { TORRENT_ASSERT(m_type == list_t); return int(m_size); } - // end points one byte passed last byte + // end points one byte passed last byte in the source + // buffer backing the bencoded structure. void set_end(char const* end) { TORRENT_ASSERT(end > m_begin); m_len = end - m_begin; } + // internal void clear(); // releases ownership of any memory allocated @@ -255,6 +304,7 @@ namespace libtorrent m_type = none_t; } + // internal ~lazy_entry() { clear(); } @@ -262,6 +312,7 @@ namespace libtorrent // this entry has its bencoded data std::pair data_section() const; + // swap values of ``this`` and ``e``. void swap(lazy_entry& e) { using std::swap; diff --git a/include/libtorrent/rss.hpp b/include/libtorrent/rss.hpp index 14ec9090e..19dce4c5a 100644 --- a/include/libtorrent/rss.hpp +++ b/include/libtorrent/rss.hpp @@ -75,6 +75,7 @@ namespace libtorrent sha1_hash info_hash; }; + // given a feed_item ``f``, add the torrent it refers to to session ``s``. #ifndef BOOST_NO_EXCEPTIONS torrent_handle TORRENT_EXPORT add_feed_item(session& s, feed_item const& fi , add_torrent_params const& p); diff --git a/include/libtorrent/storage.hpp b/include/libtorrent/storage.hpp index 2f29d4bd4..18a18863e 100644 --- a/include/libtorrent/storage.hpp +++ b/include/libtorrent/storage.hpp @@ -367,6 +367,7 @@ namespace libtorrent mutable error_code m_error; mutable std::string m_error_file; + // hidden virtual ~storage_interface() {} disk_buffer_pool* m_disk_pool; diff --git a/include/libtorrent/storage_defs.hpp b/include/libtorrent/storage_defs.hpp index d981c9d3a..3a33e2abd 100644 --- a/include/libtorrent/storage_defs.hpp +++ b/include/libtorrent/storage_defs.hpp @@ -43,6 +43,7 @@ namespace libtorrent class file_storage; struct file_pool; + // types of storage allocation used for add_torrent_params::storage_mode. enum storage_mode_t { // All pieces will be written to their final position, all files will be diff --git a/include/libtorrent/thread.hpp b/include/libtorrent/thread.hpp index 5632e8679..13fc7eb5b 100644 --- a/include/libtorrent/thread.hpp +++ b/include/libtorrent/thread.hpp @@ -57,6 +57,8 @@ namespace libtorrent typedef boost::asio::detail::mutex mutex; typedef boost::asio::detail::event event; + // pauses the calling thread at least for the specified + // number of milliseconds TORRENT_EXPORT void sleep(int milliseconds); struct TORRENT_EXTRA_EXPORT condition_variable diff --git a/include/libtorrent/time.hpp b/include/libtorrent/time.hpp index 9aea516b7..64785abfa 100644 --- a/include/libtorrent/time.hpp +++ b/include/libtorrent/time.hpp @@ -63,20 +63,32 @@ namespace libtorrent TORRENT_EXTRA_EXPORT char const* time_now_string(); std::string log_time(); + // returns the current time, as represented by ptime. The + // resolution of this timer is about 100 ms. TORRENT_EXPORT ptime const& time_now(); + + // returns the current time as represented by ptime. This is + // more expensive than time_now(), but provides as high resolution + // as the operating system can provide. TORRENT_EXPORT ptime time_now_hires(); + // the earliest and latest possible time points + // representable by ptime. TORRENT_EXPORT ptime min_time(); TORRENT_EXPORT ptime max_time(); #if defined TORRENT_USE_BOOST_DATE_TIME || defined TORRENT_USE_QUERY_PERFORMANCE_TIMER + // returns a time_duration representing the specified number of seconds, milliseconds + // microseconds, minutes and hours. TORRENT_EXPORT time_duration seconds(int s); TORRENT_EXPORT time_duration milliseconds(int s); TORRENT_EXPORT time_duration microsec(int s); TORRENT_EXPORT time_duration minutes(int s); TORRENT_EXPORT time_duration hours(int s); + // returns the number of seconds, milliseconds and microseconds + // a time_duration represents. TORRENT_EXPORT int total_seconds(time_duration td); TORRENT_EXPORT int total_milliseconds(time_duration td); TORRENT_EXPORT boost::int64_t total_microseconds(time_duration td); diff --git a/include/libtorrent/torrent_handle.hpp b/include/libtorrent/torrent_handle.hpp index 9b7386860..8c0bde18d 100644 --- a/include/libtorrent/torrent_handle.hpp +++ b/include/libtorrent/torrent_handle.hpp @@ -199,7 +199,7 @@ namespace libtorrent // expensive if done from within a GUI thread that needs to stay responsive. // Try to avoid quering for information you don't need, and try to do it // in as few calls as possible. You can get most of the interesting information - // about a torrent from the ``torrent_handle::status()`` call. + // about a torrent from the torrent_handle::status() call. // // The default constructor will initialize the handle to an invalid state. Which // means you cannot perform any operation on it, unless you first assign it a @@ -435,7 +435,7 @@ namespace libtorrent // that refers to that torrent will become invalid. bool is_valid() const; - // flags for pause() + // flags for torrent_session::pause() enum pause_flags_t { graceful_pause = 1 }; // ``pause()``, and ``resume()`` will disconnect all peers and reconnect all peers respectively. @@ -993,12 +993,12 @@ namespace libtorrent // ``info_hash()`` returns the info-hash for the torrent. sha1_hash info_hash() const; + // comparison operators. The order of the torrents is unspecified + // but stable. bool operator==(const torrent_handle& h) const { return m_torrent.lock() == h.m_torrent.lock(); } - bool operator!=(const torrent_handle& h) const { return m_torrent.lock() != h.m_torrent.lock(); } - bool operator<(const torrent_handle& h) const { return m_torrent.lock() < h.m_torrent.lock(); } @@ -1023,8 +1023,10 @@ namespace libtorrent }; + // holds a snapshot of the status of a torrent, as queried by torrent_handle::status(). struct TORRENT_EXPORT torrent_status { + // hidden torrent_status(); ~torrent_status(); @@ -1034,6 +1036,7 @@ namespace libtorrent // a handle to the torrent whose status the object represents. torrent_handle handle; + // the different overall states a torrent can be in enum state_t { // The torrent is in the queue for being checked. But there @@ -1076,6 +1079,7 @@ namespace libtorrent checking_resume_data }; + // the main state the torrent is in. See torrent_status::state_t. state_t state; // set to true if the torrent is paused and false otherwise. It's only true